Structuring information
From TechWriter Wiki
Contents |
Key points
Make sure that the reader can move through the document in a logical manner. This includes:
- Placing information where they expect to find it;
- Providing self-explanatory headings;
- Creating a logical progression (for example, placing the high-level overview before the detail);
- Indicating where the user should turn to next (for example, including "For more information..." or "Related Topics" information).
This last point is especially important when providing user instructions. Here, you should always make sure that the user know which activities to carry out, in what order, which of these activities are optional (and under what circumstances), and provide navigation around these. For example:
- Do this
- Do that
- If x occurs, you need to do something else, as described on page x, before continuing with Step 4.
- Do the other.
Organization
Have a logical order for sections (generally, the order in which they will be required - e.g. installation instructions before operating instructions.
Consistency
Provide a consistent layout across sections in a manual, manuals in a documentation set, and topics within a suite of on-line help files. As far as possible, for documents of the same type, provide the same sections, in the same order, and with the same layout. For example, if a suite of help topics describe how to carry out specific tasks, then each topic could have `Before you start', `Instructions', and `What to do next' sections. Users will then soon learn which sections they need to refer to, even when they don't read the entire document.
Images
If you provide icons to draw attention to specific points, then make sure that these do not dominate the page layout. Graphics have a tendency to catch the reader's eye, and will be the first thing they see in a page of text. This may be what you want, but if a warning applies to a specific step halfway down the page, then encouraging the reader to start reading from halfway down the page is probably not really what you want to do.
Warnings, cautions, and notes
User documents should include all of the warnings that appear on the machinery (from the EEC Machinery Directive)
BS 4899 identifies the following categories of notes:
- Warning
- Used to indicate potential injury or death
- Caution
- Used to indicate possible damage to the product or process, or property
- Note
- Used to provide supplementary information
Warnings and Cautions should immediately precede the instruction or text to which they relate.
Consider the use of icons to highlight notes, but make sure that these are not intrusive. May be industry-standard symbols.
Consider aligning notes to a different grid-line to the main body text.
