As a technical writer, you'll typically have to create indexes for the print books and for online helps you develop. The type of index we mean here is the classic back-of-book index that shows page numbers on which topics and subtopics occur within the book. An online index is much the same except that you supply hypertext links rather than page numbers.

Index in a print document

Index in an online-help system (left panel)

Rough-Drafting an Index

As with any writing project, there is a rough-drafting phase for indexing. And of course, you need to think about your audience—who they are, how they'll use the index, why they'll use it, and what sorts of terminology they might be accustomed to. After that, here's what to do next:

  1. Convert each heading into multiple index entries. Headings are a good place to start: they indicate topics and subtopics—precisely what an index does. However, don't just copy headings directly into an index and walk away. As you will see below, you need to cross-list heading-based entries in as many ways as practically possible.
  2. Cross-list each entry. Rearrange each of your heading-based entries in as many practical ways as you can. For example, a heading such as "Changing screen resolution" can be indexed as "screen resolution, changing" as well as "changing screen resolution." You might also include "resolution, changing screen." These cross-listed entries attempt to anticipate all the likely ways a reader might look for this topic in an index: "screen," "resolution," or "changing."

    Here are some additional examples:

    Heading Index entries
    Optimizing Video Display video display, optimizing
    optimizing video display
    display, optimizing video
    Playing Streaming Multimedia streaming multimedia, playing
    playing streaming multimedia
    multimedia, playing streaming
    Networking Basics networking
    networks
    Introducing Streaming Multimedia streaming multimedia
    multimedia, streaming

    Notice that you can't always cross-list index entries on every word. For example, "introducing streaming multimedia" in the preceding just wouldn't work. Would any reader ever look for this topic starting with "introducing"?
  3. Create synonym entries. Readers don't necessarily use the same terminology as you do in your documentation. They may call a diskette drive a "floppy drive." They may refer to a display as a "monitor." As an indexer, you must anticipate these common variations in terminology. In the preceding entries, it would be a good idea to have a synonym for "video display" such as "monitor." But instead of repeating the page numbers, use a See reference. That way, you point readers to the preferred term. (Of course, if there is only one page number, just repeat it with the synonym entry.)

    Here are some additional examples:

    Index entry Synonym entries
    volume, adjusting loudness, adjusting
    transmission rate speed, transmission
    capturing video copying video

  4. Review the text for additional index entries. It's ordinarily not enough just to index by headings. You have to dig down in the text for concepts, terms, and tasks that are not represented by the headings. For example, under the heading "Creating a Multimedia Stream," you might see definitions of "capturing" and "encoding." These are important terms, but they appear nowhere in the headings—index them too! In this case, you'd want to create these additional index entries: "capturing streams" and "encoding streams."
  5. Index front and back matter. Don't forget to dig around in the preface, safety notices, appendixes, and other such peripherals for additional index entries. Typically, technical-support numbers and addresses are shown in the preface. Index them—and don't forget to create cross-listed entries and synonym entries for them as well.

    Index entry Cloned and synynom entries
    technical support support, technical
    help desk
    problems

Revising and Finetuning an Index

Once you've brainstormed all the index entries that you can think of, it's time to see what the index looks like and start working it over. To revise a rough-draft index:

  1. Build a first-draft index. Once you've created as many index entries, cross-listings, and synonyms as you can, it's time to "build" a first draft of the index. Unless you are working the old-fashioned way with index cards, you can get your software application to do this for you. For example, if you work in a desktop publishing system, you've gone through your text inserting index entries. The same process applies to help-authoring tools. When you build the first-draft index, don't be dismayed. It's just a rough draft, to which you'll need to apply several kinds of revision.
  2. Toss useless entries. In the preceding steps, you've been rough-drafting the index. In that phase, you don't get hung up about the exact phrasing of entries or the likelihood that anybody would ever use them. But now is the time to start weeding out the entries that no reader would ever use. For example, first-level entries beginning with "introducing," "using, "about" are not likely to be useful. Delete them! But don't delete them from the built index. Go back into your document and get rid of the original index entry.
  3. Consolidate entries with similar phrasing. You'll also find lots of entries that have only minor variations in phrasing. For example:

    Rough-draft entries Revised entries
    technology, streaming multimedia
    technologies, streaming multimedia    		 technologies, streaming multimedia
    video display
    video displays    		 video displays
    change screen resolution
    changing screen resolution    		 changing screen resolution

    As you can see in these examples, singular/plural entries and verb variations are the most common causes of similar phrasing in index entries. Your house style may dictate using singulars as opposed to plurals. Whichever way you handle these, just be consistent.
  4. Group similar entries. You'll also see entries that need to be grouped and subordinated. For example, they may all begin with the same word, but have different modifiers. Here's an example:

    Similar entries Grouped and subordinated entries
    projector, defined
    projectors, compiling
    projectors, considerations
    projectors, creating
    projectors, troubleshooting

    		projectors

    compiling

    considerations

    creating

    defined

    troubleshooting

  5. Rework entries with excessive page entries. Some organizations have actual style-guide rules concerning how many page references following an index entry are allowable. Three is a common maximum; two is aggressive, ambitious. For example, "programming syntax, 12, 45, 74, 122, 219, 222." A string of anonymous page references like this helps no one. Instead, identify the subtopic for these page references. Here's a example:

    Too many unidentified page references Subordinated and labeled entries
    projectors, 124, 136, 154-155, 156 157 projectors

    compiling, 154-155

    considerations, 156

    controls, 136

    defined, 124, 136, 157


    A very good touch you don't often see in indexes is the page range on which a topic is discussed—even if there are subentries. If it were accurate, you could have entry like this: "projectors, 126–137"
  6. Look for entry groupings. A nice useful touch in indexes is to hunt for ways that you can group entries. For example, imagine a user guide that explains the various dialog boxes that pop up in the application. There's the Password dialog box, the New User dialog box, the Delete User dialog box, and so on. How about repeating all those entries under "dialog boxes"?

    Entries Grouped entries
    (entries are scattered throughout the index)
    Add User dialog box
    ...
    Delete User dialog box
    ...
    New User dialog box
    ...
    Password dialog box     		Add User dialog box
    ...
    Delete User dialog box
    ...
    dialog boxes

    Add User

    Delete User

    New User

    Password

    ...
    New User dialog box
    ...
    Password dialog box

  7. Look for shift-up entries. In your indexing work, you may have some subentries that need to be copied out as main entries.

    Entries Shifted-up entries
    (entries are scattered throughout the index)
    batteries

    disposing, 33

    explosion warning, 34

    manufacturer recommendation, 34

    polarity, 33-34

    purchasing, 33

    replacing, 33-34

    tabs, 33(illus)

    		batteries

    disposing, 33

    explosion warning, 34

    manufacturer recommendation, 34

    polarity, 33-34

    purchasing, 33

    replacing, 33-34

    tabs, 33(illus)

    disposing, batteries, 33
    ...
    polarity, batteries, 33-34
    ...
    warning, battteries, 34
    ...

    In this example, the indexer thought some (probably not many) readers would look up "polarity" first as opposed to "batteries, polarity." Similarly, the indexer thought people might look up "disposing" first. Even though possibilities like these are small, put them in the index anyway.
  8. Look for See also and additional See references. Toward the end of your revising phase, take a look at your index for the possibility of See also references. See also references are for closely related terms that readers might choose by mistake. For example, in the old DOS systems, there was the copy command and the xcopy command. The two commands are so closely related in name and in function that you'd want to put See also references to each other. And don't forget the See references: those point readers from synonym terms to the terms you prefer to use and index by in your book.
  9. Check the style and mechanics of index entries. The organization for which you work may have its own house style guide or refer you to some standard style such as the Chicago Manual of Style. Look at these very carefully for how they tell you to capitalize and punctuate index entries. Indexes commonly use lowercase on all nonproper-noun entries, but a certain percentage do use initial caps on first-level entries. Most styles have you put a comma just after the index term and before the page numbers; but a few do not. Some styles require you to use the same highlighting in the index as you do in the main text. If something is bold in the main text, they want it bold in the index too.

    Note: This chapter uses a variety of punctuation and capitalization styles—not to confuse you, but to make you aware of stylistic variability.

    One common index style Another common index style
    projectors, 123

    compiling, 154-155

    considerations, 156

    controls, 136

    defined, 124, 136, 157

    project profiles, 451-461

    		projectors

    compiling 154-155

    considerations 156

    controls 136

    defined 124, 136, 157

    Project profiles 451-461


    Notice in the righthand example that there is no comma between the index term and the page references. Also, you'll find that some indexing standards and styles disapprove of having a page reference on an index entry that has subentries: for example, "projectors, 123" in the lefthand example. Why isn't the page 123 reference down amongst the subentries? Just what is the subtopic on page 123?

I would appreciate your thoughts, reactions, criticism regarding this chapter: your response.