Online Technical Writing: Indexing








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 an online-help system

The following gives you a relatively quick system for creating a thorough, functional index, for either print or online

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. Tools like RoboHELP and FrameMaker lure you into this trap — just don't go there. Instead, "clone" each headings as many times 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 cloned 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 clone 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"?
  2. 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 Synynom entries
    volume, adjusting loudness, adjusting
    transmission rate speed, transmission
    capturing video copying video
  3. 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."
  4. 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 cloned 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, clones, 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 FrameMaker, you've gone through your text inserting index entries. The same process applies to RoboHELP. 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 plural. 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 over 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

  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 mentions 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.

    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 123

    compiling 154-155

    considerations 156

    controls 136

    defined 124, 136, 157

    Project profiles 451-461


    Notice in the righthand example, init caps are used on the first-level entry only, not on subentries. Notice too 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." Why isn't the page 123 reference down amongst the subentries? Just what is the subtopic on page 123?
Interested in courses related to this page or a printed version? See the resources page. Return to the main menu of this online textbook for technical writing.

Information and programs provided by hcexres@io.com.