Indexing for technical writers

Topic status automatically displays here - do not remove.

Bookmark this topic  Print this topic

By Colin Ramsden, June 2007.

The importance of indexing cannot be understated. The index has long been shown to be the primary point of entry for users when searching for information in a printed book, and this methodology has transferred directly to online documentation including help and PDFs.

For an analysis of indexing versus search usability studies, see Usability study report for online documentation

A good index assists the user to find the information they're after, through the use of both common and topical keywords and actions. A recent focus has been towards providing a user-centric, or task-based approach to indexing, to complement the traditional functionality-based or topic-based indexing.

A bad index contains entries which provide no user assistance, and contribute no alternative keywords, as shown in the following highlighted HTML Help index entry for troubleshooting DSA:

See that the highlighted index entry contributes no additional information. Both "DSA" and "troubleshooting" have been repeated in the same index entry. Very poor indeed. The source FrameMaker (FM) index marker nominates the four levels of hierarchy for this ridiculous index entry:

It turns out that this should be two separate index entries. Here's how they look after being suitably corrected:

Note the semi-colon between the index entries to separate them in FM, and the leading spacing for each entry level, to make the entry more human readable in FM. See also, that suitably adequate details were added to each of these entries ("servers cannot connect"), qualifying them from other entries in the same subject categories.

All it takes is some lateral thinking, and attention to detail. One typo, and it breaks the usability of the index, as shown above.

For that matter, the other index entries for this topic are equally dubious. The first entry "DSA: servers cannot connect" places the secondary "servers cannot connect" beneath the primary "DSA". This is a duplication of the entry that was just fixed under "DSA: troubleshooting". An examination of the existing index structure for the "DSA" primary entry as shown in the previous example above, reveals that these DSA entries are the only DSA entries, so would exist adjacent to each other in the index listing. I don't see how that assists the user in any way. Even if they weren't the only DSA index entries, they would be alphabetically sorted next to each other anyway, with "s" for "server", and "t" for "troubleshooting", so I'd still question the usefulness of this index duplication.

The second index entry "connection problems: DSA" has been ill-conceived as well. 

 

Who am I? > find out more