Readability/Usability/Quality 1-02 (March 2002) by Melanie Doulton

Indexing has been a passion of mine ever since I began writing technical documentation. An index is the key to a book, and without one a technical book cannot be used fully.

There are scores of books on technical indexing that are really useful in teaching us how to create an index the right way, with the least amount of stress, while keeping up with the documentation development lifecycle. This is, of course, when you do not have the luxury of a full-time indexer. That, so far, has been a dream in the various companies I have worked at and not a very coveted one at that.

Usually it is left to the writers to put whatever indexing skills they have into practice. The theory goes that it is best to index as you write. Usually this is feasible, with the embedded indexing features that are provided with packages such as FrameMaker, Word, and so on. But even being an indexing enthusiast, like me, does not always guarantee that this will happen. From experience, you tend to get so caught up in the process of writing, structuring, organising, and reviewing documents, that taking time out to index breaks your train of thought.

However, this is not true for projects that involve only updating specific parts of a book. Adding documentation for new functionality tends to be limited to adding precise chunks of information in various parts of a book or documentation set. This makes it easier to index as you complete each chunk. On the other hand, writing a new book where information is never stable and needs to be constantly reorganised, makes it difficult to get a handle on the structure of an index. It also reduces motivation to create an index that will need a lot of rework later.

 

Last-minute Indexing Plan of Action

The practice of indexing tends to be left until the technical and editorial review phase at the earliest, or the copy-edit phase at the latest. This tends to put a lot of pressure on the writer, and sometimes on other team members. So here are a few tips to minimise the stress and pressure, while still producing a good, usable index.

1. Budget some extra time for indexing during the last part of the project if this is not already part of the delivery process. For example, I usually tend to do a full copy-edit and proofread my book once the book is stable and most of the reviews are complete. So I plan for more than the required time to copy-edit to give me time to incorporate an index in my book.
2. Create draft entries on paper as you edit. This usually helps you decide the structure of the index. During the copy-edit process, you are better able to correlate entries that need to be linked. However, the actual fleshing out of the index can be done when you start to index the book. The following are some tips to aid you while creating draft index entries during the copy-edit:

• Use vocabulary that appears in the book.
• Create a list of first-level index entries as you go along. Match capitalisation and spelling to that used in the book.
• Make a note of the wording and types of phrases used while you are copy-editing and creating draft entries.
• If you have time, match this list to the indexes of other books in the same documentation set.

 

Indexing Quick Tips

Once the basic index has been created, the remaining steps to polish your index are standard. The following are some quick tips:

• Create a maximum of three levels of index entries.
• Create concise entries. Do not create phrases or clauses as entries.
• Make sure no entries begin with a preposition or article. Eliminate unnecessary adjectives.
• Index only major instances of a topic. Do not index every instance as you would for a concordance.
• Index synonyms and competitors terms for actions and terms used in the book to further aid users.

• Check at least five to ten percent of the index entries to make sure they point to the correct page.
• Add See and See also cross-references if necessary.
• Make sure that you do not have two separate entries because of different casing. For example:
  indexing, practice of, 3-5
  Indexing, practice of, 3-5
• Of course, run a spell check.

• Bonura, Larry S., The Art of Indexing, 1994, ISBN: 0-471-01449-4
• University of Chicago, The Chicago Manual of Style, 14th Edition, ISBN: 0-226-10389-7
• Brusaw, Charles T., Alred Gerald J., Oliu Walter E., Handbook of Technical Writing, 5th Edition, ISBN: 0-312-16690-7
• Mulvany, Nancy C., Indexing Books, ISBN 0-226-55014-1

"transline Deutschland - Übersetzungsdienst für technische Übersetzung"