Indexing
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).
For example:
creating
making
job descriptions
job descriptions
creating
The verb
Make the verb as specific as possible. Use the gerund form, and do not capitalize.
Examples:
- accessing
- adding
- copying
- creating
- deleting
- editing
- exporting
- importing
- interpreting
- saving
- scanning
- searching
- testing
- unlocking
- verifying
Note: Overly general works such as “using…” or “working with…” or “settings” are not useful index entries.
The noun
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.
Examples:
setup tasks
objects in the API
troubleshooting
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
- Formatting
The goal is to prevent fragmentation of the index, as in this example:
toast
making
toasting
toasted bread
making
toast with jam
making
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.
General tips
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.
Suggested resources
Society of Indexers (U.K.)