8   Writing and Production Software

Tables of Contents, Indexes, and Cross-References

Don’t manually create your table of contents, index, and cross-references—use your word processor to generate them automatically from markers that you place in the document. These features are essential for revisable manuals that will change frequently. To make these features work, you’ll need to first create a master document.

Some online authoring tools automatically insert links or jumps from your table of contents, index, and cross-references to the corresponding section of the manual. The links from the table of contents are based on your use of heading styles. The links from the index are from marked index entries. The links from cross-references are from marked target sources (what the cross-references are to). The ability to automatically generate links requires that you use these word processor features. If you intend to create both print and online versions of your manual, these automated features may save you time if links can be inserted automatically.

Tables of Contents

If you’ve applied heading styles to all of your headings, you can simply generate the table of contents automatically once the text and page breaks are finalized (see Figure 8-3). If you have to change the text later, remember to regenerate the table of contents.

Figure 8-3: Microsoft Word’s dialogue box for generating a table of contents

Indexes

Indexes can be built by hand by going through a print copy of the manual and creating a word processor file of entries and sub-entries (and sub-sub entries if necessary) and their page numbers. The word processor can alphabetize them for you. While this is probably the fastest way to prepare an index, each time you revise the text, you’ll have to carefully check the index for changes or new entries—a time-consuming process.

For revisable manuals, a better strategy is to mark the entries in the word processor file (see Figure 8-4). You can include both entries and sub-entries as well as cross-references to other index entries.

When the manual is finished, generate the index automatically. Your word processor will compile the entries and sub-entries with their page numbers and format them in the way you specify. Edit the index for duplications, omissions, and errors, going back into the word processor files to make your changes. Remember, if you simply revise them in the compiled index, the next time you regenerate it, you’ll have to make the same corrections again.

Figure 8-4: Microsoft Word’s dialogue box for marking an index entry

While it takes a bit longer to set up an automated index, revising it after each manual revision will be easy since you need only mark new entries, then regenerate the index.

For more information, see Chapter 4.

Cross-References

If you want to refer the reader to another section or heading, you can enter the number of the page on which the information is currently located. For example, “For more information on styles, see page 12.” While it’s easy and fast, each time you revise a section of the manual, you’ll have to locate all references to that section and check that they’re still accurate.

A better strategy for revisable manuals is to insert the reference using your word processor’s cross-reference feature (see Figure 8-5). You can refer the reader to specific headings, figures, tables, or other elements of the text and the word processor will automatically insert the correct page number into your reference. And every time you print the section, your word processor will check and update the page number if necessary.

Figure 8-5: Microsoft Word’s dialogue box for inserting a cross-reference

Creating a Master Document

The automated table of contents, index, and cross-reference features were designed assuming that your entire document is contained in one word processor file. If, like most manual writers, you’ve divided the manual up into a series of files, you’ll need to use the master document feature to make these other features work (see Figure 8-6). Otherwise you won’t be able to prepare a table of contents or index for the whole manual, and cross-references won’t update properly.

Figure 8-6: Use your word processor’s online help for information on master documents

A master document temporarily compiles the sub-documents that make up the manual into a whole manual. For a revisable manual, the sub-documents would be the modules (either chapters or sections), as well as the sections at the front and back.

To generate the table of contents or index, create a master document, then use these features in the master document. Cross-references will work as long as you are referring to other sub-documents within the master document. Beware—this process does not always work smoothly.