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?