The Top 10 Indexing Errors Made by Technical Writers

By Lorne Griffith | Senior Member

As a first-time judge in a local STC competition some years ago, I was pleasantly surprised by the quality of the entries. Of the five manuals submitted, three were award winners. At the same time, I was astonished by the poor quality of the indexes, which ranged from appalling to merely bad. Many technical communicators, it seems, are confused about what should and should not be indexed, and make common mistakes in organizing and formatting their index entries.

10. Do not index introductory material.

Sections such as "About this Manual," "Getting Started," and "Who Should Read this Guide"—while often useful in themselves—do not require inclusion in your index. When was the last time you looked up the term "who" in an index to find out whether you were reading the right manual? And if you did want to know who should read this manual, you could turn to the front of book and find the section easily.

My rule of thumb is pretty simple. If the page locator is a single digit, it probably shouldn’t be in the index.

9. Do not index the primary product name.

The primary product is the subject of the book that you are indexing. For example, Adobe FrameMaker would be the primary product in a book called Getting Started With FrameMaker. You do not need an index entry for "FrameMaker" because the name is implied in the title of the book itself.

8. Do not index topics mentioned in passing.

An index is not a concordance, an alphabetical list of all the words that appear in a given document. Rather, it is an alphabetical list of entries—some found in the document and others not—that point to a significant discussion of a topic, not merely a casual reference to it.

Consider the following example: "Like the copy command, the move command can only be performed by a system administrator. To move a file, you. . . ." In this passage, the copy command is mentioned only in passing and should not be indexed. The real topic of the passage is the Move command.

7. Do not use a double-level entry when there is only a single subentry.

Double-level entries are only required when you have two or more subentries. If you have a single subentry (for example, "files/copying"), the correct format is "files, copying."

6. Do not list multiple subentries with the same page number.

Subentries with the same page number should be grouped whenever possible. If all subentries refer to the same page, consolidate them at the main entry level.

5. Do not assign page references to both the main entry level and the subentry level.

Page references should always be assigned to the lowest level entries.

The page reference for the main heading (page 29) is confusing. Does it refer to a general overview, definitions or miscellaneous information that the indexer was unable to fit into another category?

To avoid confusion, page references should always go on the lowest-level entries. If a main heading has subentries, the page references should be with the subentries (not on the main heading), and if subentries have sub-subentries, the page references should go on the sub-subentries.

4. Do not index adjectives and adverbs.

Generally speaking, the first term of an index entry should always be a noun or a gerund (that is, a verb ending with "ing"). Do not use adjectives, adverbs, or prepositions as the first term of an index entry.

3. Do not double space or use excessive space before or after subentries and subsubentries.

Excessive line spacing between each subentry can double the length of the index, making the manual longer, heavier, and harder to handle. Not only is it a total waste of trees, it also reduces retrievability because the poor reader has to flip through twice as many pages to find the entry they are looking for. It is equivalent to double spacing a list or a telephone directory.

For a perfect example of this problem, take a look at the index in any printed Adobe manual. Some of these indexes are over 50 pages long because of excessive line spacing!

Likewise, to save space and improve retrievability, avoid single-column indexes.

2. Do not use general verbs such as "using xyz" as main index entries.

It is a general rule in technical writing that headings should contain a verb. Sometimes the verb is significant (for example, "Importing graphics"), but often it is not. When the verb in the heading is not specific and meaningful, do not use it as a main entry in your index.

1. Do not omit the index!

The only thing worse than a bad index is no index at all. Some will claim that full text searches are quite satisfactory and eliminate the need for indexes. Nothing could be further from the truth. Full text searches suffer from the following limitations:

They do not work at all if the user searches for the wrong term. For example, if the user searches for "maternity leave" or "pregnancy leave" and the topic is discussed as "family leave."
They retrieve every occurrence of the search term, including trivial ones of no interest to the user.
They point the user to the page containing the search term, but not to the actual paragraph or phrase.

Indexes, on the other hand, offer the following advantages:

Their concisely worded entries are much easier to scan than the long wordy sentences retrieved in a full text search.
They support "See Also" references that point the user to related topics.
Their hierarchical structure with nested subentries and subsubentries shows the relationship between topics in a way that the "flat" structure of a full text search never can.
When a topic has multiple subentries, the user discovers information about a topic that he or she didn’t know. In other words, when searching for A, the user may discover B and C as well.

Lorne Griffith is a freelance technical writer working out of Toronto, Canada. He has worked in the field for over 20 years, has won two STC awards, and has served on the jury of local competitions. Technical writing allows Lorne to indulge in his two special interests: indexing and graphic design.