An Introduction to Indexing
The index is an important part of any book or help file. Many users use the index to find information. If the index is poor, the users are less satisfied with the documentation.
A good online index:
- Provides multiple entry points. All the reader’s guesses result in an entry point.
- Includes consistent access routes.
- Follows users’ ideas.
- Is very detailed.
- Ensures quick access to information.
- Is easy to read.
Which words to use
Most topics have at least one noun and one verb as the first word of an index entry. Users look for words that describe the specific tasks they want to perform (the verb), or the object of that task (the noun).
Make the verb as specific as possible. Use the gerund form, and do not capitalize.
Note: Overly general works such as “using…” or “working with…” or “settings” are not useful index entries.
When documenting software, we include the names of all (or most) controls, commands, and objects that are mentioned.
Exceptions: Do not include OK, Cancel, etc.
Use the plural form. Index entries in English are usually not capitalized.
List items in categories
It can be useful to users when you list items in categories.
objects in the API
Note: “Troubleshooting” can be a very useful category. Many topics can be indexed into this category, even if troubleshooting was not the primary purpose of the topic. Users find this very useful. Be sure that the second-level keywords describe the problem that the topic solves.
Always refer to the existing index (if any)
When you are indexing, always refer to the existing index to verify
- Word form usage
The goal is to prevent fragmentation of the index, as in this example:
toast with jam
Note: Special care is required when two indexes are merged. When you edit an index that is to be merged with another one, have the other one open for viewing.
Use synonyms (or cross-references)
Synonyms are necessary in indexes for many reasons. Examples of synonyms to be used in indexes:
adding <-> new <-> creating
editing <-> modifying
locked <-> unlocking
Index style (English)
Different countries have different styles for their indexes.
In English indexes we most often:
- Use lowercase letters, except with proper names or when referencing something is capitalized, for example in software GUI.
- Use the gerund form of verbs.
- Use the plural form of nouns.
Check the keywords in similar or related topics to see what words were used
Example: If you are indexing a topic called “Inserting X into a transaction”, look at other topics about inserting things into a transactions. If the job was done right the first time, existing topics already include the word forms and synonyms that are needed. You can often copy existing keywords over to the new topic and modify them for the new topic.
Be open to others’ suggestions
If someone reports they can’t find something in the document but you know it’s there, ask what words (if any) he or she looked for in the index.
Society of Indexers (U.K.)