by Lori Lathrop, Lathrop Media Services
Webmaster note In Part 1 of this two-part series, Lori answers the following questions:
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!
Lori Lathrop (http://www.indexingskills.com/), author of An Indexer's Guide to the Internet, provides indexing services for corporate clients, professional organizations, and publishing houses throughout the U.S. and
Canada. She also delivers her two-day workshops, the "Indexing Skills for Technical Communicators" and the "Advanced Indexing Skills Workshop for Technical Communicators" for corporate clients and writers' organizations.
She is a Past President of the American Society of Indexers and, currently, she is ASI's international representative and ASI's correspondent for The Indexer (the professional journal of the affiliated indexing societies).
In addition to Lori's answers..
Convince your manager..?
Conduct a little focus group with a group of new users. See how (or if) they locate the information, without an index - and document your findings!
How big does a book need to be..?
Do a test yourself. Find a few shorter books/guides/manuals without indexes and see how frustrated you get. Will you flick through a shorter book, but not a longer one? What size of book would you not be prepared to flick through to find what you want? Lori mentioned 10+ pages - I'd go with that personally.
How big should an index be?
I have often come across the 7% figure, i.e. that the index should represent about 7% of the complete text. That seems reasonable and any guides I have produced have naturally been within 5-12%. It really depends - I would not stick rigdly to a percentage though.
How long does it take to create an index?
Again, this varies. If you take the main headings nad sub-headings in a document and index those, then take the main concepts or tasks (if these two are not identical) and index those, throw in a few see and see also references where appropriate, then add a few older terms and point to the newer ones... that should take you several hours. I have spent a minimum of 5 hours on recent projects, to a maximum of 35 hours. I would allocate 3 days, just to be sure.
What is the best time to create an index?
Well it certainly cuts down on processing time, if you create the index as you go along. Then, you can spend afew hours tidying up at the end.
However, you are unlikely at that start of writing, to have worked out a system for consistently naming items, concepts, objects, ideas and the like. So, if you have allocated time at the conclusion of a project, then you could have time to develop a system, which will mean you need less time to tidy up. I recommend leaving it 'til the end.
What do you mean by useful access points?
Well, use a smattering of see and see also references, use old terms that users may be familiar with to point to new terms. If you are documenting, for example, Victorian Shoes, then document Victorian and shoes, putting your sub-references where it is most appropriate.
Skimpy v none?
I tend to think that some indexing is better than none. But, at the very least, include ALL headings and sub-headings, as appropriate. And, I agree, don't rush it, no matter how little time you have allocated.
Automatic indexing tool?
The power of your mind will always out-perform that of a machine, in this case!