Technical Writers’ Companion

Table of contents in a printed manual:

Table of contents in online help:

In a printed manual, the table of contents, along with the alphabetical index, is the most important means of navigation.

Only omit the table of contents in a printed manual if the manual consists of less than about 10 pages and has very few sections.

Among online help developers, there’s an ongoing discussion whether the table of contents should be visible by default, and whether online help needs a table of contents after all. Some argue that a table of contents is essential; others argue that most users prefer a search box because this is what they’re used to from the web.

Full-text search (similar to full-text search with a search engine such as Google) can be fast when you don’t know where to look, but it can be slow if you want to return to a page that you’ve read before. In addition, full-text search can’t provide any logical and didactical sequence, and it can’t provide any context into which the given information is embedded.

So, as a general rule:

▪If you’re documenting complex software that users use on a daily basis, always supply a table of contents. Users need to understand the system from scratch. They need some structure that guides them through the process. When they encounter a problem while working with the product, they need to be able to come back to a help topic and find what they’ve missed or reread what they’ve forgotten.

Configure the help so that when it’s called the table of contents is visible by default.

▪If you’re documenting software that’s fairly intuitive, users won’t have to read much documentation. A typical example of this would be a small utility or web application that you use from time to time, but not on a daily basis. Here, a table of contents isn’t essential. Using search to find a particular piece of information is often faster.

Configure the help so that when it’s called the index or a search box is visible by default.

When creating online help, many help authoring tools let you decide whether you want to synchronize the table of contents with the visible help topic.

▪When the table of contents is synchronized, if you jump to a help topic via the index, via search, or via a link, the title of the new topic is highlighted in the table of contents. If the table of contents was collapsed, it’s automatically expanded as required so that the entry can be seen.

▪When the table of contents isn’t synchronized, the highlight in the table of contents remains static until the user clicks a new entry. This helps the user to come back to a particular topic after clicking links. The disadvantage is that the topic that’s highlighted in the table of contents isn’t always the same topic that’s currently shown, which may be confusing sometimes.

Tipp:
When possible, enable synchronization. Synchronization better visualizes the topic’s global context and makes navigating to related information easier. Readers learn where to find a particular topic within the table of contents. If they need to come back in the future, they can access the topic directly rather than taking the same route that took them to the topic the first time.

Synchronized table of contents:

In a printed manual, you can shorten the main table of contents by moving the entries for subchapters to the beginning of a main chapter and by creating a mini table of contents (mini TOC) there.

The pros and cons of mini TOCs are:

▪When using mini TOCs, the main table of contents becomes a lot shorter.

▪To find details, users have to move from the table of contents to the mini TOC, which adds one more step to the navigation process.

Tips:

▪Only use mini TOCs if your authoring tool supports it. Setting up mini TOCs and keeping them up to date manually is only rarely worth the extra effort.

▪Consider using mini TOCs if you have a long and complex structure with many subchapters. (However, when possible, better simplify your structure and trim your document instead.)

▪Don’t add mini TOCs if you have a full table of contents that lists the subchapters as well. Using mini TOCs in this case would be redundant and would just bloat your document.

▪Don’t use mini TOCs in online help. This just doesn’t make sense because headings in the main table of contents are usually collapsible.

Table of contents when section beginnings don’t have mini TOCs:

Table of contents when each part begins with a mini TOC:

A table of contents doesn’t necessarily have to look like the classical table of contents in a book or like the typical tree view in most help systems. Especially in online help, you can sometimes use a much more intuitive and more memorable visual metaphor. To find a suitable presentation, it helps to think of a table of contents as a map or flowchart.

You can use alternative forms of tables of contents both for the global table of contents and for mini TOCs.

Examples: