Equipping Writers for Success
The Writing Life
This free script provided by
by Barbara Vega
Return to Business & Technical Writing · Print/Mobile-Friendly Version
Can you give us an overview of indexing as it relates to technical publications (i.e., for the software industry, manufacturing, scientific work environments, etc.)?
Indexes are as important to your documentation as your documentation is to the product. Just as it would be difficult, if not impossible, for people to use your product without any documentation, it is equally difficult for people to use documentation without a good index. "Good" is the key word in the last sentence. Good indexes provide multiple entries for every useful nugget of information.
When you index your documentation, you should take several things into consideration:
Filtering those considerations through your mind will help you select index entries that meet your readers' needs.
What are the basic techniques of indexing?
Your question covers a lot of ground! Here's a two-part answer: First, I know that many technical writers and new indexers ask: "How do I know what's indexable?" or "How do I select index entries?" Fortunately, I have a simple answer: Create index entries that meet the "Happy to be here!" criteria. In other words, create entries that point to information that either tells readers how to do something or provides important details. Index entries that point to passing references do not meet the "Happy to be here!" criteria.
Your index entries should be both specific and concise. As you gain more experience in indexing, you will find it easier to create entries that balance being specific with being concise.
You should also look for opportunities to refine, expand, and enhance your index entries. For example, the technique used most often is to "double post" entries; in other words, ask yourself if your subentries would also be appropriate as main headings. The other common techniques for expanding the index include rearranging word order (when it makes sense), using synonyms (be careful with them!), and adding entries for concepts.
What comprises a truly usable and quality index for a technical publication?
Keep in mind that usability is like beauty. It is in the eye of the beholder. What is useful to you at this particular moment may not be useful to you next week. Also, information that is useful to you may not be useful to a coworker.
Quality is a little easier to define. A quality index is one that is accurate and complete, free of errors, and consistent in style and terminology. Unfortunately, as easy as it is to define quality, achieving it is not always accomplished as easily. We are, after all, human. We all make mistakes. Our fingers occasionally land on the wrong keys, resulting in embarrassing typos. Seeing errors like that always makes me wish the writer had taken just a little more time to edit the index before submitting it for production.
Indexes that fail to provide multiple access points to every useful nugget of information contribute to user frustration. That frustration can easily snowball into far more serious problems, causing customer satisfaction (perceptions of the quality of the documentation, the quality of the product, and the quality of the company) to plummet.
While we are talking about quality and usability, I will give you some quantifiable measurements pertaining to indexing. A good rule of thumb is that you should have one double-column page of index for every twenty pages of text. That equates to approximately 5% of the text. Most writers can index 10-12 pages per hour. Of course, they may be able to index more pages if the text is not dense with indexable terms and concepts, and they will index fewer pages per hour if the text is quite dense. That estimate does not include editing time, which should take at least 25% as much time as the indexing process takes.
What constitutes user-centered design of an index?
User-centered design, as opposed to a product-centered or organization-centered design, is as follows:
Good indexers have a "crystal ball" in their heads that helps them apply audience analysis skills to their indexes, creating entries that end users are likely to use in searching for information. You need to know how novices, experienced users, and everyone in between will look for information -- and provide appropriate entries for them.
Tip: Novice users will look for main entries that point them to broad terms and concepts, and your subentries will provide them with "topic analysis" that helps them understand the finer points. More experienced users will look for main headings that take them directly to those finer points. Therefore, when you "double post" subentries as main headings, you are making your index more usable for advanced users.
Should all types of technical publications be indexed? Which should and shouldn't? How do you decide?
Almost all technical publications should be indexed. There are very few exceptions. Possible exceptions include documentation that is under twenty pages or documentation that contains nothing but lists or tables and very little text.
No doubt, you are wondering about command reference manuals, which are organized alphabetically. However, don't forget that users are likely to look for task-oriented index entries that point them to the commands they need to use. How many command names have you seen that do not contain any clues about their purpose?
How important is indexing for online help/online documentation?
I believe that indexes for online documentation are even more important than indexes for printed documentation. Something happens to most people when they get online. It's similar to what happens to me when I get behind the wheel of my little Mazda Miata convertible: I want to get there now, and I don't want anything to get in my way! Similarly, most people become more impatient when they are online. They want instant gratification, and they become impatient if they do not get it.
Readers want index entries that take them directly to the information they need in just split seconds so they can get back to work. They do not want to go on a "fishing expedition", which is what they are forced to do if all they have is full text search that yields a gazillion irrelevant hits, does not provide them with any real "topic analysis" and, most importantly, cannot distinguish between significant information and passing references.
What are the most common pitfalls that writers encounter in indexing?
I think the most common pitfall is not allowing sufficient time in documentation schedules for creating good indexes. One of my clients had the best guidelines I have seen for determining how much time to allow. They said writers should plan to spend as much time creating an index as they would spend developing a major chapter for the book. What an eloquent way to put it!
Another pitfall, especially when writers do not have enough time to create a quality index, is resorting to what I call the "hit or miss" approach: quickly eyeballing files and tagging text that catches their eye for index markers. This approach invariably results in indexes that are imbalanced and incomplete. Also, of course, those indexes are sure to frustrate readers who know they have seen the information somewhere in the documentation but are unable to find it again when they need it.
Readers are equally frustrated if locators (page references or hypertext links) for index entries fail to direct them to the information they want. That is especially true for online documents when the sheer size of the documents may cause readers to think that scanning the document for the information they need would simply be an exercise in futility.
When readers are frustrated by an index, whether it's an index in a printed book or an index for an online document, the book or document and even the product lose credibility. At that point, the customers are likely to call a hotline or customer service for help and, unfortunately, they become even more upset if their call is placed in a queue and they're forced to wait for the next available service representative. Calls to hotlines are costly to product developers as well as to end users, costly in terms of dollars and also in terms of customer satisfaction.
The moral of this story is simple: A well-written, comprehensive index increases customer satisfaction and reduces costly product support time because it makes your products easier to learn and use.
This article may not be reprinted without the author's written permission.
Barbara Vega is Manager of Documentation at a software company in Costa Mesa, CA. She has served as the public relations manager for the Society of Technical Communication, San Gabriel Valley Chapter (http://www.stcsgv.org) and has over twelve years' experience as a technical writer and educator. She has written technical/business documentation for a variety of applications: software, electrical and mechanical engineering, banking, financial analysis, and personnel policies and procedures. She does freelance work as an editor for El Boricua online newsletter (http://www.elboricua.com) and has written several other articles for internet publications.