|
|
||
|
|
Basic Indexing Techniques | |
By: Lori Lathrop
October 1997
If you're like most technical writers, you have had little (if any) training in creating indexes for the documents you produce. Even technical writers who graduate from Technical Communication degree programs receive little or no training in writing indexes. Consequently, most technical writers learn indexing "by the seat of their pants " and, unfortunately, many of the indexes they produce fall short of readers' needs.
Developing a comprehensive index that contains entries for every useful nugget of information should be at least as important as every other task involved in writing your manuals. In fact, to paraphrase one of my clients, you should plan to spend as much time developing a useful, comprehensive index as you spend developing a major chapter for your manual. The index, after all, is the most important retrievability aid you can provide for your readers.
When corporations embark on quality improvement programs, documentation groups must focus on the quality and usability of their technical manuals. Surveys, Voice of the Customer (VOC) efforts, and other customer-interview strategies often uncover users' complaints. Many of these complaints pertain to users' difficulties in obtaining the information they need ... and that's generally when technical writers and documentation managers realize the need for better indexes in their product documentation.
This realization presents an opportunity as well as some challenges: How can technical writers, who are expected to possess a wide variety of talents--writing both printed and online documents, researching, planning, interviewing sometimes-reluctant subject matter experts, editing, creating graphics, juggling product schedules that slip and slide, and demonstrating expertise in whatever hardware and software the corporation uses--become proficient in indexing, too? Where does one start?
One of the questions I often hear is: "When should I start indexing the manual?"
As a technical writer, you face a dilemma here, too. If you index as you write, you can create entries while the material is still fresh in your mind and, of course, you can save yourself considerable time when you're in "crunch mode" at the end of the production cycle. Fortunately, most DTP applications provide the ability to create "index tags" as you write. Unfortunately, however, the indexing tools available in DTP programs are woefully inadequate. A misconception many writers have is that whatever they tag as an index entry is automatically a "good" index entry. Of course, that's as wrong as thinking that anyone who knows how to use DTP software is automatically an expert writer! Like writing, indexing requires skill.
The real disadvantage in indexing with DTP software is that you are "indexing blind"--you can't see what the formatted index looks like until you generate a printout. Consequently, you must be sure to allow yourself enough time to edit, refine, and enhance your index at the end of the production cycle. Also, if you index as you write, you must be certain that your index reflects any changes you make to the document. And, if you opt to postpone the task of indexing until you have a Final Draft, you must be certain that you allow yourself enough time to create a comprehensive, quality index. Otherwise, you risk putting yourself in the position of having so little time to create the index that you won't be proud of your work, and your readers won't be satisfied either.
Indexing as you write has some advantages that can help you as you develop your documentation. In addition to the time you can save yourself at the end of the production cycle, you can also use the index as an editing tool. The three main advantages of indexing as you write include the ability to resolve:
Tip: The best way to index as you write is to work on the index either after you complete a chapter or a main section of the book or after you send drafts out for review.
If you are still unconvinced that indexing as you write is the best approach, you must be prepared to devote a large block of time solely to the task of indexing at the end of your production cycle. That's a risky approach, and it's not a viable option for most technical writers; at least, it wasn't feasible for me in my previous life as a technical writer. In my current life as a professional indexer, however, I almost never create an index before the client sends me final page proofs. When the page proofs arrive, I generally have very little time (often less than one week) to create the index. As you might expect, I always find typos, grammatical problems, inconsistent terminology, stylistic problems, and organizational problems that probably would not have made it into the book if the writing, editing, and indexing were not mutually exclusive tasks.
Another question I often hear is: How long does it take to create an index for a technical manual? The answer to that question, of course, depends upon several variables, such as the complexity of the document (which translates to the "density" of information), the writer's skill (which determines whether or not the document is well-written), and the writer's indexing expertise (which determines the number of pages/hour the writer can be expected to index).
Although these variables can have a huge impact, estimating 10-12 pages/hour is a good "rule of thumb" to use in estimating how much time it will take you to create an index for technical documents. Consequently, if you have written a 200-page manual, you should allow yourself at least 17 to 20 hours to create the index. Keep in mind, however, that editing, refining, and enhancing the index will require approximately 25% to 30% of that time, so you should add another 4 to 6 hours. In other words, you should allow at least 21 to 26 hours for indexing and editing/refining the index for a 200-page technical document.
Now, let's cover some basics of "how" to go about indexing. You need a "crystal ball in your head" as you analyze the document! If you have done an audience analysis, you should know who your readers are. And, if you know who your readers are, that knowledge should help you create appropriate index entries for those readers. Some questions to ask yourself about your readers include:
In addition to helping you write the document, knowing your audience helps you create index entries that provide multiple access points that make it possible for your readers to retrieve the information they need. Perhaps many of your readers are familiar with competitive products. If so, your index should include cross-references that help educate them; for example, if you know that some of your readers are programmers who are familiar with attributes in some programming languages but that your product refers to attributes as properties, you should create a See reference like this:
A See cross-reference helps educate your readers. It also provides a means of vocabulary control because it directs them from a term that is not used in the document to the proper term. By the way, as a technical writer who is familiar with the product technology, you are the best person to create the index. You have the advantage of knowing if the name of a feature in this version of the product was called something else in a previous release. That knowledge helps you create appropriate See references to direct readers from the old name to the new name.
The other type of cross-reference, See also, points readers to additional or related information; for example:
Finally! Let's answer the question every new indexer asks: How do I select index entries? You've found the time, analyzed your audience and the document, made some notes to yourself about terminology issues requiring cross-references, and you're ready to start indexing. Where should you look for your entries? Try the following:
In addition, depending upon the decisions you made about the scope of the index, you might also create entries for:
Tip: You can't always use the exact words you see in the book. Chapter headings are often task-oriented, and that's great. However, readers are unlikely to look under G for getting started, under U for using virtual functions, under I for introducing the product, or under H for how to use the tutorial. Readers might, however, look for installation options, virtual functions, the product name, or tutorials.
Let's take a look at the text below (from an earlier paragraph in this paper) and select some appropriate index entries:
As you think about the index entries you would create for the above paragraph, keep in mind that no two indexers will develop an index in exactly the same way. Also, there are likely to be significant differences even if the same indexer creates an index for the same document at two different points in time! Even so, each index should contain entries for many of the same terms and concepts. If I were indexing the above paragraph today, I would probably create these entries:
index development time importance of
By the way, the only reason I would create a subentry for development time is because I know there is another reference to it in the text. If that were not the case, you could say that I had over-analyzed the text. New indexers are often guilty of over-analyzing the text --or rewriting the book in the index. Of course, just as many new indexers err in the other direction, missing significant entries and creating a skimpy index that has minimal value to readers.
Let's analyze one more paragraph:
This paragraph has more meat, so to speak. What entries would you create for it? Among the possibilities I see are:
customer satisfaction surveys documentation managers realizing need for better indexes index usability concerns interviewing customers product documentation development challenges quality and usability of quality improvement programs readers complaints technical manuals. See product documentation technical writers responsibilities usability user complaints Voice of the Customer (VOC)
Actually, I may not be inclined to create all of these entries. I simply wanted to give you an idea of some possibilities. How many of them would you have created? If you were editing an index with the above entries, would you delete any of them? If so, why? Could you combine any of the entries? Would you refine the wording for any of these entries? Would you consider any of the subentries as candidates for main headings (primary entries)?
We've touched on several indexing considerations. As you index a document, your mind is filtering the information to determine what terms and concepts to index. At the same time, you should be weeding out insignificant entries and asking yourself questions about your choices. Your goal is to create a comprehensive index that includes entries for every useful nugget of information without being guilty of over-analyzing the text. Also, don't forget that you can use your index as an editing tool to improve the quality of your documentation.
For more information, contact Lori Lathrop at Lathrop Media Services.
© 1997 Lori Lathrop, all rights reserved.
|