Editor’s Note: The following piece by Lori Lathrop is part of our collection of “classics”– technical communication articles that stand the test of time no matter how many technologies come and go. What do you think? Do the tips provided in Lori’s Indexing FAQ apply to technical content beyond books? How can index terms, and keywords help drive usability?
I need to convince my manager that our documentation needs indexes. Give me some ammunition to do that.
Explain to your manager that an index is as important to the documentation as the documentation is to the product. The best documentation in the world is essentially useless if readers are unable to retrieve the information they need. The “three strikes and you’re out” rule is a good guideline to follow here. After three unsuccessful attempts to locate the entries they are looking for, most readers give up on the index. If they are unusually persistent, they will try to use other methods, such as using the table of contents or simply eye-balling the text, to access the information. If those methods also fail, they may resort to calling the company’s technical support service in the hopes of getting the needed information. Of course, by the time they do that, smoke is coming out of their ears! In addition to losing faith in the index, they may also lose faith in the documentation, the product, and even the company. In other words, the quality of an index is directly related to customer satisfaction.
Tip: I once read that a satisfied customer will tell at least three other people; however, a dissatisfied customer will tell at least a dozen other people!
How big does a book have to be before it requires an index?
A few of the guidelines I have seen specify that any document over 20 pages should have an index. A couple of other guidelines I have seen said 10 pages, and one style guide I saw at a corporate client’s site said 17 pages. My standard answer to this question is, “It depends.” What sort of documentation is it? How dense is it with indexable terms and concepts? When you can answer those questions, you should be able to come up with your own rule of thumb on how large a document should be before it requires an index.
Tip: The size of your pages is another factor to consider.
How big should the index be?
When I worked as a technical writer for IBM, the guideline we used said we should have one page of double-columned index per 20 pages of text. That works out to approximately five to six index entries per page. Another way to look at it is to figure that the index should be at least five to six percent of the text.
Tip: It is not unusual for documentation that is dense with indexable terms and concepts to have an index that is well over five to six percent. Also, documentation that is not as dense (such as procedures manuals or documentation that includes a lot of source code or illustrations) might be a bit under five to six percent.
How long does it take to create an index?
The most elegant style guideline I have seen suggests that you should plan to spend as much time creating the index as you would spend writing a major chapter. I can’t think of a more eloquent way to put it! I generally say that most technical writers can index approximately 10 to 12 pages of text per hour.
Tip: My rule of thumb does not include editing time. You should plan to spend approximately 25 to 30 percent of your overall indexing time editing the index.
When is the best time to create an index?
As I always say, everything in life is a trade-off. If you wait until the final draft is finished, you need to be sure that you have allocated sufficient time for creating a quality index. If you do not allow sufficient time, your index may get “short shrift” and, consequently, the quality of the index and its usability will suffer. On the other hand, if you index as you write, you will need relatively little time to create entries for definitions, acronyms, and other “easy” entries that do not require a lot of analysis. Then, when you have more time to devote to analyzing the text, you can create a comprehensive index that contains multiple access points for every useful nugget of information.
Tip: Indexing as you write allows you to use the index as an editing tool to improve your documentation. By indexing as you write, you can identify inconsistencies in terminology, organizational problems (when information is scattered throughout the text), and imbalances (when two or three topics of equal importance do not receive equal treatment in the index).
What do you mean by “multiple access points for every useful nugget of information?”
You can refine, enhance, and expand your index by:
- Double-posting qualified subentries and sub-subentries as main headings
- Rearranging word order to create additional entries (only if the word order makes sense!)
- Creating entries for synonyms
Tip: Be very careful with synonyms. If readers do not find the index entry on the specified page, they will feel misled and, once again, the credibility of your index suffers.
Is it better to have a skimpy index than to have no index at all?
No! A skimpy index is probably what I call a “hit or miss” index. That’s what happens when you rush through the document, haphazardly highlighting terms to throw into index markers. Although you may select some good index entries that way, chances are you will also miss many good index entries and the result is a less-than-usable index.
Tip: The best indexing tool you will ever find is a highlighter (the old-fashioned kind)!
Can you recommend an automatic indexing tool?
No. Can you recommend an automatic writing tool that would just scan the product and automatically create the documentation for it? That said, when I index FrameMaker docs, I use IXgen, an add-on tool developed by Frank Stearns & Associates.
Tip: The processing required to create an index happens between your ears, not on your hard drive!
Why do we need an index when we have full-text search?
I wish I had a dollar for every time I’ve been asked this question! First of all, I believe that indexes for online documentation are even more important than indexes for printed manuals. Why? It has to do with human nature. Something happens to most of us when we get online. It’s similar to what happens to me when I get behind the wheel of my Mazda Miata convertible. We want to get there now, and we don’t want anything to get in our way! Although full-text search can be helpful, it does not
- Provide topic analysis
- Distinguish between significant information and passing references
- Create meaningful cross-references that show how topics interrelate
- Resolve differences in terminology (when multiple terms are used interchangeably).
Tip: For more details about topic analysis, significant information, meaningful cross-references, and terminology differences, see the next four questions.
What is “topic analysis?”
Topic analysis is the real value of an index, which provides an organization and a structure that does not exist anywhere else in the text. In addition to letting readers know what topics are discussed in the document, a good index actually educates readers by providing an orientation to terminology as well as to hierarchical relationships (revealed by subentries and sub-subentries). Full-text search cannot educate readers in this way.
Tip: The topic analysis your index provides should satisfy expert users as well as novice users. To satisfy your expert users, ask yourself whether your subentries and sub-subentries would also be good as main headings and, if you think they would be, “double post” them.
How do you distinguish between significant information and passing references? In other words, how do you determine what is “indexable” and what’s not?
Ask yourself, “Will the reader be happy to be here?” In other words, does the index entry point to a definition of something, a detailed explanation of something, or procedures describing how to do something? If the index entry does not do any of those things, chances are, it is a passing reference and, if that’s the case, the reader will feel it was a waste of time and will not be happy to be there.
Tip: Although full-text search is very good at finding every occurrence of terms, it lacks the ability to determine whether or not each occurrence is truly significant. Only you possess the discretion required to do that.
What do you mean by “meaningful cross-references?”
See and See also references, which full-text search cannot provide, are enormously helpful to readers. Index entries with See references point readers from terminology not used in the document to the correct terms. For example:
configuration options. See installation options
and
setup procedures. See installation options
Also, if a certain feature in the new release of your product now has a new name, you should use a See reference to point readers from the old name to the new one. For example,
Reports option. See QuickReports option
Tip: Think of See references as you would think of pepper in cooking. Do not sprinkle them too liberally throughout your index. Readers do not like to be bounced around the index unnecessarily.
See also references point readers to topics that provide additional or related information. Essentially, a See also reference tells readers, “If you are interested in this topic, you may also be interested in these other topics.” If you want the See also reference to point to more than one additional topic, use a semi-colon to separate them; for example:
images. See also color; video cards
Tip: See also references should point from larger topics to smaller topics, not from smaller topics to larger topics.
How can an index resolve differences in terminology?
Ideally, product documentation should look as if all of it was written by the same person. The same is true for indexes to your product documentation. Readers may become confused, wondering whether different terms are actually synonymous or, in fact, refer to different things. Using one of the examples above, if your product has only one reporting feature, which is called the QuickReports option, you should be consistent when creating index entries for it. All of your entries should be under “QuickReports option” (not under both “Quick Reports option” and “reporting feature” or “report utility” or “generating reports”). Of course, as shown in my answer to the previous question, it is appropriate to create See references to point readers from terminology that is not used in the document to the proper term. Consequently, you may also have this See reference:
generating reports. See QuickReports option
Tip: Variations on a theme are great in music–but they don’t work well in indexes!
