search

trailblazer / representable

Maps representation documents from and to Ruby objects. Includes JSON, XML and YAML support, plain properties and compositions.
http://trailblazer.to/2.1/docs/representable.html
MIT License
689 stars 108 forks source link

Documentation links hard to find on the trailblazer docs site #221

Closed sbwoodside closed 7 years ago

sbwoodside commented 7 years ago

The (internal) documentation links to the various subpages e.g. Getting Started, API, etc. are not visible "above the fold" and are not clearly connected to the content. See screen shots.

screen shot 2017-06-28 at 13 51 31 screen shot 2017-06-28 at 13 51 42
apotonick commented 7 years ago

What do you suggest to make it simpler? I thought a lot about it - maybe move the "active" section up in the sidebar?

Thanks.

BTW: the Representable docs need a makeover.

On Thu, Jun 29, 2017 at 3:57 AM, S Woodside notifications@github.com wrote:

The (internal) documentation links to the various subpages e.g. Getting Started, API, etc. are not visible "above the fold https://en.wikipedia.org/wiki/Above_the_fold" and are not clearly connected to the content. See screen shots.

[image: screen shot 2017-06-28 at 13 51 31] https://user-images.githubusercontent.com/47834/27652416-a01414f2-5c09-11e7-9ce9-01310bcdd957.png

[image: screen shot 2017-06-28 at 13 51 42] https://user-images.githubusercontent.com/47834/27652417-a21ab850-5c09-11e7-862a-403a7c629ce5.png

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/trailblazer/representable/issues/221, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAopsrg5H81rylca7QvLauFyM7Nuy9fks5sIpP7gaJpZM4OIUEc .

sbwoodside commented 7 years ago

The left side titles could collapse, i.e. only the ones that are currently displayed in bold and all caps would be visible by default, and then clicking on one would reveal the subsections. That would probably allow all of the major sections to be visible and ensure that the current section/subsection is visible.

Another great idea that AWS docs use (see e.g. http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-public-data-sets.html which I just chose at random) is to have Previous and Next links at the bottom of each page.

A lot of the docs could use a makeover. One thing that I've missed for Representable is an example for Rails that shows all of the major methods (index, show, create, update, delete).

apotonick commented 7 years ago

The collapsing sections is indeed a good idea, I remember a pull request about that. But now Trailblazer has a paid frontend developer haha!

Thanks for the Previous/Next link/idea, that's a pretty awesome idea. As soon as we actually have presentable pages (like the guides) this will make a lot of sense. Thanks again.

Example apps are coming, and the TRB2 book is something I started thinking about. We actually improved our doc tools a lot in the past 3 months and allocate more and more time for rewriting (and restructuring, which is the actual work!) - I'm confident by the end of summer (northern hemisphere) there should be most gems covered, and some neat sample apps with guides.

Have you seen the TRB book? We discuss Representable in the last 2 chapters.

sbwoodside commented 7 years ago

Great, I'm glad I was able to offer useful ideas.

I haven't seen the book. Thanks for making me aware of it. Does it offer more detail on Representable than the docs?

apotonick commented 7 years ago

Check http://trb.to - we have a new accordion sidebar now! :fireworks:

sbwoodside commented 7 years ago

Looks great