Documentation: one long page or several short pages

Question

We're working on the design and organization of our documentation. The current structure is something like this:

• General info on topic
  • specialized sub-topic 1
  • specialized sub-topic 2
  • specialized sub-topic 3

(Note that "General info on topic" is itself nested under a much broader topic, so that "specialized sub-topic 1" is at the 3rd level, but I can't make the markdown represent that.)

The question is whether to keep this multi-page, nested format or combine all the content into one page with a Table of Contents at the top.

My previous experience as a journalist tells me that readership drops off the longer your content piece (hence our current organization). But I recognize that things may have changed a little from the ink-on-paper paradigm. I've tried to do some research, but most of what I'm finding seems to be in a much more commercial context ("don't put all your ads above the fold" and so on) or about infini-scroll. This question touches on the subject, but doesn't quite address what I need.

So: long multi-topic docs pages, or short topic-specific pages? I'm hoping for studies & statistics, but will settle for anecdotal experience.

Answer 1

Agreed on previous conclusions. But then when having multiple short topics you should alow users to quickly move from one topic to another.

So having clear and visible menus, search, categorization, recommended topics on bottom, next / prev topic and other types of navigation that you will find appropriate can help.

Having real time response site in React or similiar technology, or in general having really quick response time helps a lot also.

Answer 2

Your previous experience tells you right:) According to HP article in reading and visualising data, people only take in 20% of what they read (and 80% of what they do and see):

https://policyviz.com/wp-content/uploads/2015/10/power-of-visual-communication.pdf

So if I were a reader, I would prefer to have multiple, but concise and short paragraphs or pages on each topic, perhaps even with graphics on them to show me examples that I can take in quickly, without my mind starting to wander off.

Hope this helps.

Answer 3

The short answer (as often happens) would be "it depends on your use cases". In particular, you need to think what particular affordances would be important for accessing your documentation.

Splitting text into manageable sub-sections has been called chunking in literature and has been researched quite extensively. For a few examples of such research with practical implications, have a look at these articles.

Whether the chunks are then presented on separate pages that need to be loaded each separately, or a long page with sections and anchors in it is a subsequent question that depends on the use case of your data. There are several obvious advantages of each. For the web there have been different approaches, single-page applications obviously being a prominent trend, which illustrates the range of issues. Here are a few aspects that I consider important.

Single Page

A single page would be advisable when you expect your users to download or print the documentation for offline use. Then they can do this with a very few clicks that do not depend on the number of your topics.

Another advantage of a single text is when it is used for reference. Then it easy to search the entire text with ctrl+f on most reading environments.

A downside is the "back to top" button, mentioned in your link, whereas the actual problem is that you need continuous easy access to your table of contents, and "back to top" is only one (quite old) solution for it.

Multiple pages

Multiple pages would be advisable when you have sections that you want to be readable beginning to end, thus giving users the perception that they have "closed" a topic/section by reading it all.

You would need to be conscious of typical reader screen sizes, as some pages might be so short to appear almost blank, and others might look as long-scrolling pages themselves.

It also would require good connectivity which sometimes (on mobile, in transit) might not be readily available.

Search functionality then does not come as a given by the reader device, and it needs to be available from the web platform.

Answer 4

Both.

For example, the MySQL Reference Manual is split into many small pages, but also provides links to the whole text in various formats. This may be more work than you want to spend on it, but providing a link to the whole page as HTML should be pretty trivial.

For me, reading smaller pages is always much better as it allows

• opening details in a new browser tab
• bookmarking and linking to parts

Moreover, it loads much faster(*) and you never get lost by unintentionally clicking on the scroll bar.

Anyway, you should make sure, that some global search works well. I usually rely on googling, which works best, unless for private pages.

---

(*) Ideally, you prefetch the next page and linked pages.