From TechWriter Wiki

Jump to: navigation, search



Consider how a reader will navigate through the document. Never assume that the reader will start at the beginning and read through in a linear manner until they find what they are looking for.


Provide frequent and meaningful headings to the key sections of the document. Most readers inherently understand section hierarchies within a publication. That is, they will understand that Sections 1.1 and 1.2 are sub-sections within Section 1. However, to simplify this, it is essential that the hierarchy of the sections is clear.

The section hierarchy can be emphasized way of numbering, typography, identifier, indentation, and so on. When using different typography, the most common convention is for each higher-level heading to be rendered in a larger font size than the lower-level heading immediately 'below' it. However, this must be easy for the user to identify. Generally, users can identify a three-point difference, but no lower than this.

In Science and Technical Writing, A Manual of Style, Rubens provides the following suggestion:

type size
1 18 24 12
2 15 20 10
3 12 16 8

Where it is necessary to provide a large number of headings, it may not always be possible to maintain three points of type between them. For example, with nine headings, and starting from 11 point type, the highest level of heading would need to be 38-point, which is ugly and impractical. To work around this problem, consider using an additional typographical convention, such as italics, or underlining, for intermediate levels. The problem here is that readers need to learn the convention used, and so it is advisable to use another convention, such as indentation or numbering as well.

Do not skip heading levels. For example, do not have headings at the fourth level directly under a heading at the second level. In some cases, to have all 'lower-level' information at the same level within the hierarchy it may be necessary to insert 'artificial' headings, but this will be preferable to skipping levels, which can confuse the user.

Table of contents

In all but the shortest of communications, provide a table of contents. This should include the major sections and sub-sections of the document. Depending on the type and use of the document, it may or may not be necessary to include all levels of headings that appear in the body of the document in the table of contents. For example, the document could include five levels of heading, but the table of contents only include the top two levels. The decision as to which levels will be included in the table of contents should be based on which (headed) sections a reader will want to refer to directly. That said, tables of contents may be used by potential readers to gauge the scope of the document. From this perspective, it may be wise to include lower levels of heading, even if the user will not refer to the sections directly.

As with the actual headings themselves, the hierarchy of the entries in the table of contents should be emphasized.

Consider providing multiple tables of contents, for different types of information, if this would help the reader more easily locate the specific information they are looking for. Typically, this will be only where these different types of information are accessed directly by the reader, and not necessarily within the context of the section within which it is located. It is not uncommon for separate tables of contents to be provided for illustrations or tables, but indexes for other types of indformation may also be valid.


For non-trivial documents (typically, for books or manuals, or technical documents of over (say) 40 or 50 pages), consider providing an index. Indexing is a separate discipline, and is covered separately in Indexing.

Consider providing multiple indexes, for different kinds of information. For example, a trouble-shooting manual may contain an index of possible error messages which includes reference to the pages in the manual that describes how to resolve each message. A command reference may contain an index of commands and a reference to the pages describing each command.


Although not strictly a part of the structural navigation of a document, cross-references are an essential form of navigation.

In print

Whenever referring to another section of the same document, always give the heading in full (as it appears in the document) and provide the page number, or relative position ("above", or "below"). Most word-processing applications make this very easy.


  • Refer to "Replacing the starter motor", on page 23.
  • Inflate the tyre to the correct pressure for the vehicle weight, as shown in "Recommended Tyre Pressures", below.


In on-line documentation, cross-references should be provided as hyperlinks. However, take care to indicate when the cross-reference will open a new window, or navigate away from the current site.

Consider possibility of the on-line documentation being printed out for later reference. If this is likely, provide the cross-reference in a form that also lends itself to use in print. For example, always use the full heading (and never "Click here"). It will not be possible to give page numbers, but for links within the same page, it is possible to specify the relative position. Also, consider specifying the URL of the linked page (especially when the link is to an external website).


Personal tools