The Role of Indexing in Technical Communication

Home / Archives / Back Issues 1993 /

The success of a technical document depends heavily on the index. The task of indexing a technical document often cannot begin until insufficient time remains to do a good job. However, for many users of the document, a good index is mandatory to its usability.

A good index is especially crucial for technical documents because readers tend to look up specific topics instead of reading the document from cover to cover. A poor index often frustrates readers and taints their view of the entire document.

To create a good index, you have to know what makes a good index, understand the indexing tools available, and follow the steps to producing a good index. Additionally, you must make many process decisions that affect the quality of the final index you produce. The skills and processes for creating a good index are similar to those required for most technical communication projects: methodical approach, knowledge of the user's needs, collaboration with colleagues and testing.

This paper discusses how to create a good index and how to make decisions about using personal computer word-processing tools to create an index. It also discusses the feasibility of creating maintainable indexes using these tools.

What is a Good Index?

A good index meets the needs of its readers by providing an accurate, complete, easy-to-use, access tool for the document. It tells users what the document contains, and helps readers find information within 20 seconds. A good index typically has the following features:

• A good index is written for a variety of users. In addition to the audience of the document, the index audience includes researchers looking through several books for a topic, and people referred to a specific topic by someone who knows the document. These audiences need to find information without having to know terminology unique to that document, and possibly without having to know the terminology of the subject area.
• A good index receives the same careful editing and checking as the rest of the document. The index is frequently the primary access tool of a document and gives users their first impression of the accuracy, consistency and completeness of the document.
• A good index includes secondary and tertiary entries to communicate dependencies. The index should comprise 10 percent to 20 percent of the document, one entry for every 25 to 50 words, or approximately eight to ten entries per page of your document. Be aware that an index can be too long; a concordance of key words in the document does not create an effective access tool.
• A good index limits each entry to no more than three to five page references. Instead of each listing having numerous page references, the index refines topics so that only a few page references are necessary. The index also does not contain page references where only a passing mention of the topic appears, without useful content.
• A good index uses alternative terms and synonyms to help all readers. Specifically, if the document uses terminology that is not standard in the industry, the index includes the standard terminology.
• A good index uses cross-references to show how topics interrelate. "See" references point to preferred terminology used in the document, and "see also" references point to related information.
• A good index avoids vague entries, such as:

  Avoiding paper jams 62
  Before printing 17
  Introduction 2
  Using paper 9,25

  For example, someone who does not know how to load paper into the printer is not likely to look up "using" in the index.

• A good index uses an easy-to-read format. Entries are easy to scan, and indentations clarify levels of entries.

Understanding Word-Proccssor Indexing Tools

The indexing component of today's word-processor software is currently not as well developed as other popular word-processing features. However, because users are demanding more sophisticated document publishing features, such as good indexing capability, the strength and power of word-processing systems is growing also.

Automated indexing tools enable you to embed indexing codes in your document so the computer can handle the tedium of ensuring accurate page number references. However, many problems face users who try to create a good index using today's PC-based word-processing tools, including:

• Poorly written and incomplete documentation on the indexing feature.
• Alphabetizing sort orders, based on ASCII, that do not match readers' expectations.
• Software that does not support typical indexing needs such as:
  • Including alternative items not in the document text.
  • Creating and sorting "see" and "see also" cross-reference entries.
  • Including page ranges, such as "2-1 to 2-4."
  • Using modular page numbering.
• Software that limits the number of items the index generator can process, such as:
  • The size of the files from which you can generate the index.
  • The number of files that you can link together to generate one index.
  • The number of entries.
  • The number of levels available for indenting index entries.

Most people do not consider the strength of the indexing feature when they make word processor purchasing decisions. When your first document is complete and ready to be indexed, that is not the time to learn about the shortcomings of your word processor. In fact, time is often so critical that many people give in and write the index within the limitations of the software, rather than create the good index they really want.

The Steps to Producing a Good Index

In addition to using good tools, producing a good index requires process decisions such as who should write the index and when to begin writing the index. Regardless of these choices, editing is a crucial step to the success of the index.

Who Should Write the Index?

Deciding who should write the index involves examining the trade-offs between the amount of subject matter expertise and the level of communication skill of the potential writer. These trade-offs are outlined below:

• The document author has subject matter expertise and is familiar with the structure and content of the document. However, the author may be too close to the material to include enough alternative term entries.
• A subject matter expert who is also a good writer, but not the document author, will probably take longer to index the document, but also will probably include alternative terms the author may not consider.
• An indexing expert will create a thoroughly consistent index. However, a possible lack of familiarity with the subject matter may cause the indexing expert to miss subtleties or dependencies that a subject matter expert or the document author would catch.

When deciding who should write the index, consider the skills of the individual and remember to balance good communication and indexing skills with subject matter expertise. Considering the combined skills of the index writer and the index editor is also useful.

When Should Indexing Begin?

Word-processing indexing features enable you to embed indexing codes in text as you write. While this process may seem appealing at first, most indexing experts recommend indexing after the document is finished so that you can step back from the work and give the index the same focused attention that you gave the document.

Writers should concentrate on the content of their writing and leave other concerns, such as formatting and indexing, until the draft is at a later stage. Think of the time wasted if an editor, a reviewer or a product change requires you to rewrite the document, and thus the index.

However, the advantage of being able to complete an index quickly might encourage the writer to create individual indexes as he or she finishes a section or chapter. Using this approach, the writer and editor can begin to think about indexing issues earlier in the documentation process, and reviewers of the document have a useful tool to help evaluate the usability of the document. For example, reviewers might suggest alternative terms for the index.

Of course, combining and editing the individual indexes into one complete index still takes time for the end result to be successful.

Editing: A Crucial Step

No matter which process you use to write the index, editing ensures the accuracy and completeness of the index. The editor should be a communications specialist, not the writer of the index. Roughly half of the time allocated to indexing should be spent editing. Special editing tasks for indexes include:

• Reading the complete index. Check for a consistent level of detail. Should some of the subentries be main entries, or "see also" entries?
• Making vague entries more concrete.
• Looking for appropriate cross-references, such as alternative ways to structure entries. Think again about alternative terms and synonyms for the entry you are checking. Are all likely alternatives included?
• Checking that the index uses either the singular or plural form for one topic entry, for example, "file" or "files" but not both. Using both can create difficulties in locating information, especially if other entries come between the singular and plural entries.
• Checking that subentries are in parallel form; for example, a parallel structure would be:

  character, wildcard 2-45
  directory search 2-20
  file search 2-30
  text search 2-40

  A non-parallel structure would be:

  character, wildcard 2-45
  directory search 2-20
  searching in files 2-30
  search, text 240

• Adding secondary and tertiary entries for an entry that exceeds the limit of three to five page references.
• Watching for subentries that all have the same page reference. If the readers can find all the information on one page under the primary entry, think about eliminating the subentries.

The Myth of Maintainability

With word-processing software, you can code the files for index entries, push a button, and generate the index. Theoretically, each time you revise the document, you can add, edit and delete a few index codes, push the button again, and print the updated index.

This process sounds great, and avoiding the time-consuming tedium of checking index entries by hand is certainly desirable. Although you can quickly generate an index using word-processing software, creating a good index this way is almost impossible.

In addition to the limitation of indexing tools mentioned previously, current indexing tools provide no easy way to edit the first draft index while maintaining the integrity of the indexing codes in the document.

Editing the Index File Eliminates Maintainability

If you edit a machine-generated index file, the codes in the file are no longer "maintainable." That is, if you revise the document files and press the button again, you get the index you started with and your valuable index edits are lost.

You can edit the regenerated index again to regain the value of the original editing. Alternatively, another editor can edit the regenerated index without trying to match the original editing. The problem with editing the index again is that even if the second index is better, users who were familiar with the first index may have difficulty locating items in the new index with only slight revisions.

Editing Index Codes is Time-Consuming and Frustrating

The other option, of course, is for the editor to edit the index codes themselves. This option maintains the correlation between the index and the codes; however, editing index codes is a difficult task and adds an extra level of indirection for the editor.

First-time index codes are often physically distant from the related second-level codes in the file, and sometimes they are in a separate file. You can use the search capabilities of the word processor to find related entries, but most word processors search the text as well as the index codes, and some do not search the index code text at all. This procedure requires that the editor or an assistant also be a word-processing wizard.

Usually an editor is more likely to mark up the generated index, and then the index writer or a word-processing specialist fixes the codes to match the editing marks. This procedure must include iterations to ensure that the generated index matches the editor's annotated copy.

Editing the index files and editing the index codes both take time and require a great deal of effort to preserve maintainability.

Conclusion

Creating a successful index requires time, care, thought, and attention to minute detail. Software can help keep page references accurate, but current software hinders the process of editing an index.

Maintainable indexes are difficult and time consuming to create. If the document receives major revisions, recreating the index will probably be necessary. However, if the document is expected to receive only minor revisions, creating maintainable codes may be worth the effort.

If maintainability is not an issue, use the automated tools where they are the most useful -- to create the first draft of an index. Then use standard word processing techniques to create the final edited index.