Post History

Source: https://writers.stackexchange.com/a/34138
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/34138
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/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](http://xmlpress.net/publications/eppo/)_. 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.

Original score: 20