4   Standard Contents

Index

An index is an alphabetically organized list of topics found in the manual. Include an index in manuals of 20 pages or more. Many readers prefer the index to the table of contents because it’s faster to use.

While indexes are usually found at the back, in a modular manual printed in 3-ring binders, the index is better at the front where it’s easier to get at. In a 3-ring binder, particularly larger ones, turning to the back of the manual can be difficult.

Unlike a table of contents, which lists just the headings found in the manual, an index lists the topics covered using keywords. The keywords listed can be either the words used in the text, or synonyms that readers might try to look up.

If you have several closely related manuals, consider creating a global index, which combines their indexes into a single index. The advantage to readers is they will find the information regardless of which manual they pick up. As well as the page reference, assign a prefix to designate the manual (for example, “ADM, 2-4”).

In modular manuals, which don’t have consecutive page numbering from front to back, you can’t reference page numbers as easily. You must also reference the module number (for example, “3-4” for chapter modules, or “3.2-4” for a 2-level manual). Alternatively, you can refer readers simply to the appropriate module without a page number. Referencing page numbers makes the index more time consuming to maintain, but it’s more useful.

If possible, use your word processor’s automated indexing feature to tag entries and generate the index. It will take slightly longer to set up, but you can regenerate the index after each revision to the manual. In a document contained within a single word processor file, tagging and generating the index is straightforward. In a manual composed of a large number of files, generating the index is more complicated. For more information on using your word processor to generate the index, see page 8-8.

Index entries can be tagged in the text at any time, but the index can only be generated once the text has received final approval and no other changes will be made to the files.

Indexing is best done by either the writers or editor, who knows the content of the manual, what’s important, and the best places to refer the reader to.

Index the substantive parts of the manual only—don’t index parts of the manual without information content.

Rules for Creating an Index

Don’t simply reference every page on which a particular word appears— this is not useful. Instead, list the topics found in the manual and the best place to go for information on that topic. You may have many places the topic is mentioned, but refer the reader to only one or two places.

If a topic can be referenced in several ways, include each variation (for example, include both “documentation standards” and “standards, documentation”). If there are other terms, include those also (for example, “see writing guidelines”).

When creating an index, include only the words that you think a reader might try to look up. Make sure that the entry begins with the keyword the reader will use. For example, an entry like “creating a file” is not useful since few readers would think to look up “creating.” Use “file, creating” instead. In general, the main entries will be nouns, not verbs.

Try to include other words that the reader might try to look up, even if those terms are not used in your manual.

Index entries should be divided into main entries and one or more levels of sub-entries.

Using sub-entries lets you create topic categories that enable the reader to find information more quickly. Rather than having to scan the entire index for topics, the reader can look under one category and find all the topics that relate to that category.

Don’t use a two-level entry for a single topic.

Avoid more than one page reference for an entry. If you do include several page references, bold the one the reader should try first.

Don’t list a series of sub-entries all with the same page number.

Online Indexes

Include an index in your online manual even if you have a search feature—they are not the same. Search allows readers to look for occurrences of certain characters, words, or phrases, possibly returning hundreds of ‘hits.’ An index is a list of topics contained in the manual, with links directly to where each topic is discussed. They are just as valuable online as they are in print.

The index should be accessible with a single click from every place in the manual. Set up the index so the user can click the letters of the alphabet and go directly to the entries beginning with that letter (see Figure 4-4).

Figure 4-4: Web page showing table of contents in left frame and index in right frame

If you’re planning both a print and an online manual, you can use the same index for both. Some online authoring tools will insert links automatically where you’ve marked index entries.

Unlike a print manual, which references only the page the entry is found on, a link can take you directly to the heading or line in which the tag is embedded. Make sure the entries for your online index only reference one heading or line in the manual, since links can’t jump to more than one place. Each index entry should be unique.