How to Write a Great Index for your Technical Document

Introduction

An index, as we covered in our pillar post on indexing, is a list of terms in your technical document that points to the location of the term within the document. In a printed book, an index typically appears on a separate page, often near the end.

It is an alphabetical list of words and terms, usually with definitions or explanations. It can be used to locate specific information in a technical document. It helps the reader find the exact word or phrase that they are looking for without having to read through all of the document’s text.

The goal of an index is to help readers find content more quickly when they need it.

A Quiz

A quick technical writing quiz for technical writers:

Question – what is the most important part of any technical manual?

Answer – would you believe it is the INDEX?

Why?

Because I do not know of a single technical document user who would not immediately flip over to the Index and start searching for the words and terms of interest.

And the sense of frustration and disappointment is very real when the user cannot find an Index at the back.

In the technical documentation competitions that I’ve participated as a juror, a technical manual without an Index always created on us jurors an impression inferior to a similar manual with a well-developed one. It’s always a value-added, an advantage, and never a disadvantage.

You need to provide an index and do it well if you are writing a manual over 30 or 40 pages long.

How to Create an Index

So how do you do it? What are the tricks of the trade?

First off, make sure you understand the important difference between a TOC (Table of Contents) and an Index.
A TOC presents topics in same the linear order that a reader encounters them in the book. It’s a summary (and a useful one at that) of “what comes after which topic.”

An Index, on the other hand, is an ALPHABETICAL list of the IMPORTANT TERMS and CONCEPTS covered by the manual, regardless of their location within the manual.

Thus without really understanding what the manual is about, you cannot write an Index because you would not be able to determine what is important and relevant from a reader’s (or end user’s) point of view.

That’s the reason why there are many professional indexers with their own organizations who create indexes as a lucrative full-time profession There are no professional TOC-creators, however, since it is a mechanical compilation that is usually accomplished at the click of a “Create TOC” button.
John Lindley’s “Index to the Plates” from his “Sertum Orchidaceum” published 1838 (Public domain photo courtesy of Wikipedia Commons)

Helpful Index Tips

Here are some tips to help you compile great Indexes for your technical documents:

1) Always use lower case for your Index entries. “password” instead of “Passwords”, or “boat” instead of “Boat”. Lower-case letters are easier to read in an Index than the upper-case letters.

EXCEPTION to the rule: all Proper Nouns should start with a capital letter. “Africa” instead of “africa”, or “Toyota” instead of “toyota”.

2) Always use singular case for your Index entries. “fuse” instead of “fuses”, or “capacitor” instead of “capacitors”.

3) Do not have more than 3 levels of nesting. The human mind starts losing track beyond 3 levels. Easy-to-read Indexes do not have more than 3 levels of indentation.

4) Do not use verbs for Index entries.

If possible, all your entries should be singular nouns.

If, for example, you’d like to point the reader to the page where “adding a network” is explained, create a first-level index entry “network”; then insert an indented second-level entry under it, named “adding”.

Why? Because most people would not search for “adding” as an abstract activity in itself but only in its relationship to another concrete object, like “network”. So it’s a better practice to anchor the verb “adding” to the noun “network” than the other way around.

5) If you use an acronym as an entry, always create a cross-reference to its open form and then give the corresponding page number at the open entry.

For example, your entry for MPG should be “MPG, see miles per gallon”. And then: “miles per gallon … p. 17” (just an example). Otherwise, you run the risk of confounding your readers by an unexplained acronym the significance of which remains a mystery until the reader visits that page and does further research into it.

If, on the other hand, you explain the acronym’s meaning in the Index, the reader will be saved that research and will develop more trust both in your Index and in your document.

May your work take you to the happiness and prosperity you deserve like a well-written Index!