Indexing

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

American Society for Indexing

Society of Indexers (U.K.)