Technical Writers’ Companion

The following example shows an excerpt from an owner’s manual for a car. The main table of contents follows the traditional approach of listing the topics based on the car’s components (the product structure). A supplemental, situation-based guide groups the same topics in a more user-centric way by listing them according to specific scenarios that may occur when using the car. Note that in the situation-based guide, some topics are referenced multiple times.

Users are free to choose which information path to use:

▪Users who own the car and want to explore its full set of features can use the traditional, product-based table of contents.

▪Users who rent the car for a day or two usually don’t take the time to read the manual. However, situations may arise where they do have to look something up. In this case, the situation-based structure provides them with a collection of just the information they need.

Traditional, product-based table of contents:

Additional or alternative, situation-based table of contents:

Don’t provide additional paths for minorities of users. Only provide an additional path if a significant proportion of users from your primary user group will be likely to use it.

To make your document as simple as possible, provide as few additional paths as possible. One (if any) additional path is usually enough.

You can use all main structure models that you can use for a primary information path (see Primary structure models).

For example, you can use and combine:

▪user-based structures according to user groups, expertise, use cases, scenarios, stages of use, tasks, and goals

▪time-based structures

▪product-based structures

▪topical structures

▪alphabetical or numerical structures

Many printed user manuals and reference manuals include a list of figures and a list of tables. These rarely add any significant value. In most cases, they just make the manual more bulky.

▪Don’t include a list of figures or a list of tables just because your authoring tool can create them automatically, or only because they fill a few extra pages with little effort.

▪Include a list of figures or a list of tables only if you expect that a significant proportion of users will actually use them to look up specific information. Typically, this is only the case with flowcharts and with tables that contain technical data. In all other cases, a clear table of contents and a good alphabetical index are better tools for navigation.