The Role of Indexing in Technical Communicationby Mary Jane Northrop |
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.
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:
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.
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:
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.
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.
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:
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.
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.
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:
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
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.
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.
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.
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.