11

For online, developer-centered documentation for a complex software product, which structure is going to be more usable: a smaller number of long, comprehensive pages, or a larger number of more granular pages? Which organization should I choose to make finding information easier and more user-friendly?

This is assuming each page is well-structured, has a sticky internal table of contents, and a page-wide search that can point the user to specific anchors inside the pages.

The arguments I see so far are:

  • Granular pages can contain a single piece of information per page, can be easier to consume at a glance
  • Comprehensive pages can contain all information related to a larger topic, or an overview of a whole feature
  • Comprehensive pages are better for in-page/browser searching
  • Granular pages make it easier to identify where one sub-topic ends and another begins
  • Granular pages require more clicking to browse through content

Potentially related question: What is considered an acceptable length for a technical document?

  • You might want to consider whether people will be reading your documents on a phone (or tablet) instead of a computer. – S. Mitchell Mar 9 '18 at 19:51
  • @S.Mitchell it is always possible, but not particularly likely, as the documentation is primarily aimed at developers who will be installing/configuring/extending a product that is not mobile-optimized itself. – user23425 Mar 9 '18 at 20:00
20

I wrote a whole book on this subject. It is called Every Page is Page One: Topic Based Writing for Technical Communication and the Web. In it I look at the research on how people use technical information and how the web changes how we use information generally and come up with seven principles for topic design.

One of the things I looked at in depth when preparing the book was the subject of length. My conclusion was that length is not a useful way of addressing the problem. Instead, we should think in terms of what in software engineering is called cohesion: the extent to which all the pieces in a module belong together.

A cohesive topic solves one user problem. (Not necessarily the whole problem they came with, which may be composed on several sub problems, but one discrete problem.) The number of pieces of information required to create a cohesive topic that addresses one problem can vary substantially. Therefore length is not a useful measure.

My seven principle of Every Page is Page One design are intended to provide guidance in creating cohesive topics. Following these principles should lead to topics that are the right length for the the job they have to do. The seven principles are:

  1. An EPPO topic is self contained. It has no necessary previous or next topic.

  2. An EPPO topic has a specific and limited purpose.

  3. An EPPO topic conforms to a type. When you have achieved a cohesive topic design, you will find that every topic of that type follows the same pattern, since the same information needs occur in each instance. Once you discern the pattern you can use it to guide the writing of future topics.

  4. An EPPO topics establishes context. Because it stands alone as the first topic a reader may read, a topic needs to establish its context so that the reader knows where they are and what kinds of information to expect.

  5. An EPPO topic assumes the reader is qualified. This may seem counterintuitive, but if you don't assume a certain reasonable level of competence in the reader, you will end up trying to explain everything and your topic will balloon into a book. You support readers who are not qualified by referring them to other topics.

  6. An EPPO topic stays on one level. Different readers seek different levels of information at different times in their journey to understanding. Let readers make the choice of when to change levels by changing topics. Otherwise you will not be able to follow the other principles and your topics will lack cohesion.

  7. EPPO topics link richly. Every topic is embedded in a much wider subject space. In order to keep your topic cohesive and focussed on one problem, you must not keep bringing in related subjects. But readers still need ready access to those related subjects. Links provide that access. In software engineering, the flip side of cohesion is loose coupling. Links provide the loose coupling that makes the cohesion of topics possible.

In conclusion: Length is the wrong measure. Focus on making your topics cohesive and on linking them together richly. This will produce topics of varying lengths, but each will be the right length for the job it has to do.

8

TL;DR

Short pages are better.

The Ideal Structure

I would recommend the following:

  • Each page should have a single, clearly defined purpose
  • Each pages should have a clearly defined audience
  • Pages should be linked to other, relevant pages
  • Structure your pages like a tree, with overview pages nearer the root, providing more detail as you move towards the leaves
  • Provide multiple contents pages that reflect the roles and interests of readers
  • Provide a comprehensive search facility
  • Encourage page users to contribute to the contents

In my experience, a wiki is an ideal vehicle to provide these features.

Justification

  • Most people find long pages daunting
  • It is easier to find information on a short page
  • Contents pages help clarify the structure of the documentation
  • Overview and deep-dive are separated, and are likely to be consumed by different readers (or readers at different levels of knowledge)
  • Programmers are familiar with this structure
  • Contents trees and search make this structure very navigable
  • Nobody minds clicking, especially programmers. The old two-clicks rule simply doesn't apply any more.
  • A good global search makes in-page searching less important
  • Documents produced in collaboration with their readers are generally better than those produced by a single author

About Me

I am a programmer with over 20 years experience in the industry. The team to which I belong produces some of the best documentation I've ever seen. We do this using a MediaWiki-based wiki for all our documentation. Everyone in the team contributes, edits, clarifies, corrects etc. More importantly, we all read the documentation, because we've developed it together to meet the needs we actually have, rather than the needs someone else things we might have.

  • 1
    Thanks for the insight, It's always good to hear from someone who's a member of our potential audience. And we already have an active system for contributions from both our devs and the community (using git). – user23425 Mar 9 '18 at 10:05
  • Strongly seconding good global search and a comprehensive TOC. I don't mind multiple tabs and lots of clicking if I can find what I need. – Lauren-Reinstate-Monica-Ipsum Mar 9 '18 at 11:00

Your Answer

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