Design docs file format changed from textfile to github md

[domitian]

design.textile file in docs folder is now design.md with github flavoured markdown syntax. Also fixed some typos and grammatical mistakes in that file.

[domitian]

Not able to add label to the pull request.

[bf4]

Thanks for this @domitian

I'm not sure there's much value to changing it to md, since it's really just an archival doc, but since you did the work, I'll take a look at it.

Based on your comment in #1487 it looks like a useful change would be make it more clear this not the current design. The current design is the architecture doc.

[domitian]

@bf4 got your point, I changed the name of the doc to LEGACY-DESIGN.md which should make it clear that it is not current design doc.
Added to the start of this doc that this is not current design in bold case and to have a look at Architecture doc.

[bf4]

Thinking about the file names .... Original_design and rename architecture to design? Initial_design?

[domitian]

yeah, for renaming architecture to design is good.
legacy_design if feel will give more meaning to the other doc than initial/original design, we could also think of old_design

[bf4]

initial_? legacy and old don't really convey that it was the original design doc. Maybe in architecture just link to serializers.textile in Rails (before reverted) or README.textile in first 0.0.1 commit Or the DESIGN.textline form 0-8-stable or 0-9-stable? which was the source of this?

[bf4]

while you're in here or in a new PR, we also need to change the yard docs links in the readme to http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0.rc4 since master doesn't appear to be updating.. and maybe also http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable and http://www.rubydoc.info/github/rails-api/active_model_serializers/0-8-stable

[domitian]

@bf4 created a new PR for the Yard docs links #1491

[domitian]

As per this commit from you in the past, the source is 0.8-stable.
I also did a manual diff to confirm it's source.
My suggestion is create a design folder and keep design documents for each version.

[bf4]

Well, the doc was copied from there but it originated in rails before 0.0.1. The readme references the readme's of 0.8 and 0.9 which already serve the purpose of their design

B mobile phone

On Feb 2, 2016, at 11:43 AM, domitian [email protected] wrote:

As per this commit from you in the past, the source is 0.8-stable.
My suggestion is create a design folder and keep design documents for each version.

—
Reply to this email directly or view it on GitHub.

[domitian]

So should we just remove the file and add references in architecture doc about the past design?

[bf4]

That's what I'm thinking now

B mobile phone

On Feb 2, 2016, at 9:35 PM, domitian [email protected] wrote:

So should we just remove the file and add references in architecture doc about the past design?

—
Reply to this email directly or view it on GitHub.

[domitian]

So should we link it and remove the file then?

[domitian]

Can I remove the file and add link in architecture.md then?

[bf4]

Can I remove the file and add link in architecture.md then?

@domitian Yeah, that sounds good.

[bf4]

@domitian Are you still interested in finishing this PR? #1490 (comment)