The Table of Contents – Getting it Right

This is part of the Help Authoring Tips series.

The problem with many help systems is that some help authors are still thinking in a linear world. A user manual is a linear offering. While we all know that readers don’t start on page 1 and read to page 200, they do start on page 16 and turn to page 17 before reading pages 18 and then 19. Linear movement. If they seem to have dropped into the middle of a body of information on page 18, they have the option of moving back a page, either physically with a printed document, or by scrolling with the mouse for an online format.

Help users do not recognize a linear movement through a help topic. They can jump anywhere, at any time via the search, index, and hyperlinks provided to them. The freedom this provides users should change the way we offer information. This is true in how we write, true in how we divide information into chunks/topics, and it should be true in how we design the table of contents (TOC).

In a typical for-print manual, technical writers would generate the table of contents automatically based on the structure and content of the document. If we felt a large body of text was relevant to two or three (or more) chapters in a document, we would have to either use a cross reference to indicate to a user that more relevant information can be located in another location – or copy/paste that large body of information into the file again. If we were to take this second option, the table of contents would show the duplication and we would have to worry about maintaining duplicate information sources.

In a help system, where the table of contents indicates a link to information, we have the freedom to enter duplicate links without duplicating the information. There is one topic, one source even if there are multiple access points from the table of contents. This freedom should be considered and maximized when building the table of contents for a help system.

Using many help authoring tools (certainly Adobe RoboHelp and Madcap Flare), we can now create customized TOCs. We can create customized TOCs for a particular audience; for a particular format, for different products, etc.

While you can automatically import a TOC from an existing Word or FrameMaker document as the start of your journey through help development, it is important to remember that the act of importing the document should be considered a starting point, not the end point. Once you have imported the document into your help authoring tool – examine the structure of the table of contents to verify that you have considered the optimal needs of your end user – for the format in which you plan to deliver your document or help system.

Leave a Reply

Your email address will not be published. Required fields are marked *