Review Suggested Edit

You can't approve or reject suggested edits because you haven't yet earned the Edit Posts ability.

I spent so much time trying wrestling with just this problem that I wrote a book about it: Every Page is Page One: Topic-based Writing for Technical Communication and the Web. ([http://xmlpress.net/publications/eppo/](http://xmlpress.net/publications/eppo/)).
~~The answer I came up with after much research and experimentation is that it is not about length, but about certain characteristics of the topic, which I distilled into seven principles:~~
1. A topic should be self contained. That is, it should not be written as if it followed immediately from any other topic, or as if it will be followed immediately by any given topic. It should be written as the first and possibly last page the reader will see.
2. A topic should have a specific and limited purpose. This does not necessarily mean it answers the whole of the reader's question because reader's questions, and their existing knowledge, vary too widely for that, but rather that it should complete one whole step in the reader's journey to correct action, just as a commuter train takes people reliably from their suburban station to the downtown station. Getting them from house to station and from station to office may be the work of other topics.
3. A topic should conform to a type. People usually need the same types of information to complete tasks of the same type. All recipes, for instance, have the same basic structure. Conforming to a type ensures that you are providing the right information for a topic to achieve its specific and limited purpose.
4. A topic should establish its context. Because people do not read documents or documentation sets in order, they may start at any topic, and if a topic does not establish its context, they will be lost. Any topic that cannot establish its context clearly is not a full topic but a fragment of something else.
5. A topic should assume the reader is qualified. If you start adding information for readers who might not be ready, your topic will grow into an unruly and impenetrable mess. If readers are not ready, refer them to other topics to get them up to speed.
6. A topic should stay on one level. Some people prefer to start with the details and work up to the big picture. Some want the big picture first. Let them choose for themselves by keeping each topic on the same level and providing links to related topics.
~~7. A topic should link richly to other topics. If you don't link richly, people will have a hard time finding related information and you will be tempted to violate the other principles.~~
~~(No, I'm not back, but I get a notification for new tech comm topics and it is hard not to answer a question when you have written a whole book on the subject.)~~

I spent so much time trying wrestling with just this problem that I wrote a book about it: Every Page is Page One: Topic-based Writing for Technical Communication and the Web. ([http://xmlpress.net/publications/eppo/](https://xmlpress.net/publications/eppo/)).
The answer I came up with after much research and experimentation is that it is not about length, but about certain characteristics of the topic, which I distilled into seven principles:
1. A topic should be self contained. That is, it should not be written as if it followed immediately from any other topic, or as if it will be followed immediately by any given topic. It should be written as the first and possibly last page the reader will see.
2. A topic should have a specific and limited purpose. This does not necessarily mean it answers the whole of the reader's question because reader's questions, and their existing knowledge, vary too widely for that, but rather that it should complete one whole step in the reader's journey to correct action, just as a commuter train takes people reliably from their suburban station to the downtown station. Getting them from house to station and from station to office may be the work of other topics.
3. A topic should conform to a type. People usually need the same types of information to complete tasks of the same type. All recipes, for instance, have the same basic structure. Conforming to a type ensures that you are providing the right information for a topic to achieve its specific and limited purpose.
4. A topic should establish its context. Because people do not read documents or documentation sets in order, they may start at any topic, and if a topic does not establish its context, they will be lost. Any topic that cannot establish its context clearly is not a full topic but a fragment of something else.
5. A topic should assume the reader is qualified. If you start adding information for readers who might not be ready, your topic will grow into an unruly and impenetrable mess. If readers are not ready, refer them to other topics to get them up to speed.
6. A topic should stay on one level. Some people prefer to start with the details and work up to the big picture. Some want the big picture first. Let them choose for themselves by keeping each topic on the same level and providing links to related topics.
7. A topic should link richly to other topics. If you don't link richly, people will have a hard time finding related information and you will be tempted to violate the other principles.
(No, I'm not back, but I get a notification for new tech comm topics and it is hard not to answer a question when you have written a whole book on the subject.)

Communities

Review Suggested Edit