Structuring information

From TechWriter Wiki

Jump to: navigation, search

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 knows 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:

  1. Do this
  2. Do that
  3. If x occurs, you need to do something else, as described on page x, before continuing with Step 4.
  4. Do the other.

Organization

Have a logical order for the sections of a document. Generally, this will follow the order in which the information will be required. For example, installation instructions should normally be presented before the operating instructions (because you cannot operate the equipment or application until you have installed it).

Although it is often logical to position information according to the order in which it will be required, there is also a strong argument for positioning information according to the frequency (or urgency) with which it will be required. Thus, operating instructions (referenced on a daily basis) would be positioned ahead of installation instructions (typically referred to only once). If this approach is taken, then it is important that sections are at least referenced in the order in which they would normally be referenced (so, a cross-reference or link to the installation instructions would be included (possibly as a prerequiste step) prior to the operating instructions.

The logical order of sections is most critical in a single publication. If information is split over several documents (for example, a separate installation guide and operations guide exist) then each document should reference the others, and outline the suggested reading order.

Consider also documentation that will be primarily accessed in electronic form - especially information accessed via a search function or context-sensitive help function - where the order in which the information will be accessed is impossible to predict. In these cases, each unique unit of information (for example, a single document or Web page) should provide (1) an indication as to its position within the overall documentation set, and (2) references to other (typically prerequisite) information units.

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
Advisory information in documentation that states that performing some action may lead to serious or dangerous consequences.
Caution
Advisory in software user documentation that performing some action may lead to consequences that are unwanted or undefined, such as loss of data or an equipment problem.
Note
(1) A helpful hint or other information that may assist the user by emphasizing or supplementing important points of the main text. (2) a body of free text that describes some general comment or specific constraint about a portion of a model.

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.

See also:

Personal tools
Support