Docs consolidation proposal

[billyjanitsch]

Most good docs pages (e.g. Backbone, Express) put their entire documentation on a single page. This makes jumping around much faster (cmd+F on all class methods, and no page load wait-time), and encourages top-down readability.

If the docs get rewritten with better class subheadings, would you consider consolidating the Mn docs into a single page on the docs site, with a full, ordered index in the sidebar? I'd be happy to implement this if there's agreement.

Related: #214

[peterblazejewicz]

I think that's an argument from a point of experienced developer - a quick, one page reference doc is sometimes better. But please consider someone who just poke around concepts of each solution and is trying to get some information on some key points of given project:
backbone model
express router
marionette application
angular controller
ember controller
Which of above gives a better learning experience when searched via indexing engines? Which will provide more condensed resource? In fact Backbone and Express won't even lead to expected resource on the first click or second click. For Express I'm using Dash, not web page, as Dash is better indexing Express documentation:
https://cloud.githubusercontent.com/assets/14539/8391842/6bcc7c2a-1cd2-11e5-90a4-2814c299d394.png
So my point is: I'd rather provide additional, single-page documentation, not-indexed alongside with existing one.
Thanks!

[billyjanitsch]

@peterblazejewicz Thanks for your thoughts! I completely agree that the docs should be very accessible to first-time users. To be more precise, I'm describing the following two changes:

1. The sidebar would be ordered by functionality and contain class methods like Backbone's.
2. The class docs would be concatenated onto a single page so that clicking on a class/method in the sidebar that you are not currently browsing scrolls the page instead of reloading it, (see e.g. Backbone.Model#changed).

If I'm understanding correctly, your concern is that if someone Googles e.g. "marionette collection view", they would land on the main docs page as a result of change (2) and be confused. That's a valid concern, although it's worth considering that the current CollectionView docs aren't necessarily the best place for them to end up, since they make reference to a lot of other Marionette concepts (View, Region) as dependencies. Maybe the main docs page actually is always the best place to send new users (especially if it is improved to contain a high-level overview). The user would get a sense of Marionette's main features before moving on to their resource of interest. It requires an extra click, but could result in less confusion.

Alternatively, maybe the solution is, as you suggested, to continue statically rendering the docs for each class on separate pages, but to provide a "full docs" page for power-users.

Regardless, how do you feel about change (1), independent of change (2)?

[paulfalgout]

I am actually 👍 for 1 + 2. Solves having to add search

[ianmstew]

I would rather have separate pages for SEO, but I like the "full docs" page for power users.

[paulfalgout]

I think maybe we should look into https://github.com/GitbookIO/gitbook