Technical Writers’ Companion

Fonts:

▪If space is limited, use a narrow font for the table of contents. If you use Verdana for the topic text, for example, Arial is a good narrower choice for the table of contents. Use the same font size as the body text within the topic area.

▪Unlike in the table of contents of a book, use the same font and the same font style for all hierarchy levels.

Indentation and symbols:

▪Indent subtopics.

▪If you can configure it, don’t use plus-minus icons and connecting lines in front of the topic icons. They add little value and lots of clutter.

Color:

▪Don’t use bold colors for the topic icons because they don’t contain important information. Instead, use fairly pale colors or shades of gray.

▪Likewise, don’t use a bold color to highlight the selected topic. Inverted text (white on dark gray) is perfectly good enough for highlighting the selected topic. Reserve color for highlighting important information in your help content. If you don’t like a black-and-white table of contents, use one basic color that you already use somewhere else. For example, use your corporate color, the predominant color of your product logo, or the color used in the tab that brings up the table of contents.

No:

Yes:

If your topics match particular information types (see Structuring: Distinguish information types), you can use a dedicated topic icon for each information type. Readers can then see immediately from the topic icon which kind of information a topic contains before they even read the heading.

In the topic icons, you can use colors, symbols, or a combination of both.

Instead of indicating the information type, you can also use special topic icons to indicate:

▪new topics

▪topics of particular importance

▪topics for particular user groups

Even a small difference in the icon design can give a hint:

When possible, configure your authoring tool so that topics can be opened with a single click rather than with a double click. A single click better matches what users are used to from surfing the Internet.

Some help authoring tools allow you to configure whether an entry collapses when a user jumps to another topic. The advantage of having the previous entry collapse is that users always only see a small part of the whole structure, which helps them to focus on the section that they’re currently browsing. The downside is that they can’t see the complete structure all at once.

As rules of thumb:

▪In very long documents, make entries automatically collapse.

▪In short documents and in medium-sized documents, allow multiple chapters to be expanded simultaneously.

When possible, enable synchronization of the table of contents with the topic that’s currently shown. When a user jumps to another topic via a link, via search, or via the index, the table of contents then automatically expands at that position and highlights the newly selected topic.

▪The advantage of synchronization is that users can constantly see their current position within the table of contents, which improves orientation.

▪The disadvantage of synchronization is that users need to use the Back button if they want to return to the topic from where they’ve started. In the early days of the Internet, this was a problem because many users didn’t know how to use the Back button. Nowadays, however, this usually isn’t a problem, so in most cases enabling synchronization is the better alternative.

A table of contents doesn’t necessarily have to look like the ordinary collapsible table of contents.

If the table of contents is short, its items don’t have to be collapsible. This works especially well on mobile devices with small displays. In its most simplistic form, a table of contents can just be a static list of topics.

Depending on the subject of your document, you can sometimes use a good visual metaphor relating to physical objects or workflows. Occasionally, you can design a table of contents as a flowchart, or as an organizational chart.

The visual table of contents can replace the classical table of contents completely, or you can use it in addition to the classical table of contents. This is one of the few opportunities in technical communication where you can really be creative.

For your inspiration, the following pictures show some examples of “tables” of contents that use a visual metaphor: