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.

posted over 6 years ago

CC BY-SA 3.0

Kramii Reinstate Monica‭

15 reputation 0 3 3 0

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.

posted over 6 years ago

CC BY-SA 4.0

Mark Baker‭

4371 reputation 12 1104 744 58