1

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.

enter image description here

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?

Examples of single-page: Bootstrap, express.js, Umbrella JS (my own).

Examples of multi-pages: jQuery, Webpack, Stripe.

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?

  • 1
    Your documentation is all just describing the existing methods. I'd expect to see that on one page with a persistent left-nav (for example, Bootstrap has a persistent right-nav). It would get annoying to have to click and load page after page to view the different method details. Often, during development, I don't know what method I want/need to use. It's beneficial to have them all on the same screen. Now, if you had a separate topic that described, for example, "Getting Started" or "Examples" then, those would be appropriate separate pages. – maxathousand Jul 18 '17 at 18:57
  • @maxathousand Sorry if I wasn't clear; it'd be split in different sections, but each section then would have its own methods in one page like in the current docs. Do you think something like this would work for you? A tiny description on the top of each section. – Francisco Presencia Jul 18 '17 at 19:03
  • 1
    Yeah, that makes sense to me. I find that longer documentation pages allow me to browse more freely. It might just be personal preference though... – maxathousand Jul 18 '17 at 19:17
  • The One page solution is also shareable and indexable. – cameraman Jul 20 '17 at 15:21
1

No matter which model you use, try experimenting with the type hierarchies on the page. Reading (and comprehension) is the single most important activity on a documentation page.

My personal opinion: the one page model you have works well.

Type hierarchies: Have clear distinctions between content and navigation

Right now you have a dark purple color along the edges. Maybe it's my eyes, but it seems to crowd the content (my sole reason for being there).

If you look at models like the bootstrap docs, and express.js, the sidenav typography is smaller, giving more space to the content. The active link is also given some distinction (bootstrap using a border left):

Bootstrap example

enter image description here

Here a quick browser tools hack for your nav (just a starting point):

enter image description here

  • reduce the documentation title so it's not as prominent (it shouldn't compete with the h2 in your content pane)
  • bold and color change for active link
  • removed background purple to emphasize the content

I know this is not the original focus of the question. You have a nimble docs page right now; just saw an opportunity to prioritize readability perhaps. (just my 2 cents).

  • The purple thing I did it naturally on my own; then the documentation size I totally agree, just done it. The bold+color change for the scroll part will take a bit more work, right now the default section is open in the right page. See the changes (F5). Thank you a lot for those tips. – Francisco Presencia Jul 18 '17 at 20:09
  • Yeah! coming along. Actually, come to think of it, you may not even need the menu title saying 'Documentation'. Maybe delete for a sec, see if you need it. – Mike M Jul 18 '17 at 21:21
  • Now it is also a link to come back to the main page from any page. I added some nice hover effects. – Francisco Presencia Jul 18 '17 at 21:24

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.