Keep the Structure Simple¶
Documents, like tutorials and manuals, are read from cover to cover. New information is based on what the reader already knows.
Technical documentation is not valuable as a standalone product but only in combination with a certain software product. Therefore, the reader must be involved in doing something with the product as soon as possible. Any digression makes it harder to follow the story and breaks the comprehension of information.
Rules¶
-
Do not give references to future sections which actually require knowing more than the reader knows at the point of reference.
-
When writing release notes, make sure to list the new version on top of the release notes list. Users seek new information so we should provide the easiest way to find it.
- Structure the text in such a way that the reader is involved as soon as possible
- Do not introduce graphics or tables as if they are a continuation of the current sentence.
- Notes are a way to give additional information which actually does not belong to the current topic
Sometimes, however, it is hard to determine if a given paragraph belongs to the current topic or should be treated as additional information. In this case, do not transform this information into a note but start the sentence with !!! note.
Created: June 26, 2023