Post History

Source: https://writers.stackexchange.com/a/12429
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

What goes into your index will be defined by your readers' needs. How will they use your book? Will they come in with knowledge of (and vocabulary from) a related subject? Are they experts or novices or some of each? An index's primary job is to have an answer when somebody comes to it with a question.

Here are some guidelines that I've learned over many years of doing technical writing. I never formally learned this and style guides don't tend to cover indexing in any detail, so this is just one person's accumulated experience:

- Index entries about operations get at least two entries, one for the noun and one for the verb. People might try to find out how to insert a whatsit by looking under either "inserting, whatsits" or "whatsits, inserting".

- Use those index entries _everywhere_ they're relevant, not just the first mention. For example, do you have a "troubleshooting" section that covers problems with inserting whatsits? Index that; if somebody's having trouble inserting his whatsit, you want him to find that. If your index never lists more than one page number for an entry, you're probably missing something.

- Standardize your verbs early. You don't want to have some of your entries under "inserting" and others under "adding", unless there are precise technical differences between the two. If there _are_ such differences, consider see-alsos under the two verbs. As for which verbs to use, I know this sounds circular but you want to use the verbs that your readers will naturally reach for, so there's a "know your users" issue here.

- Index concepts (things people need to _know_, as opposed to things they'll _do_) if your readers might reasonably need to look that up, but not if it's passing or unimportant. Don't fill up your index with too much "just in case" entries; they make it harder to find the ones people actually need. (In a digital copy you can be more generous because people can search, but for paper, make it easy to use.)

- Find some way to test your index. Nobody ever seems to review those carefully, but maybe you can do some informal user testing. If you have access to reader feedback after release (bug reports, for example), look closely at the ones where there _was_ documentation but they apparently didn't find it.

- In my experience gerund verbs and plural nouns are most common as index entries.

Original score: 7