What way should the documentation of a site be, all in one page or split into different pages? Since I think it is relevant, this is my project documentation right now, a library for Node.js development for new users.
All in one page advantages:
- No waiting to load the next page. Note: my docs are mainly text; otherwise (with images) I'd think there'd be tradeoff.
- Smooth transitions among sections, both because of "just scrolling" and because of smooth behavior on the left nav.
- Can be printed (not sure of how many people do it though).
Different pages advantages (current implementation):
- Easier to reason about. Now I am learning the concept X. Then the concept Y.
- Contextual. It is easier to get hold of where you are if the page is short than if it's really long. Even more if you get lost.
- Less scary for new users. Analogy: A 700 page book is certainly more scary than a 80 page one. My library is aimed to beginners.
- Shareable: you can just share a single page.
- Indexable: Google will index each method if it's in a different page.
So, how should I choose which one is preferable? Any advice?
Note: since the biggest and best in the field use multi-page, what is the reason for it? Is any of the single-page disadvantages too big?