by Lori Lathrop, Lathrop Media Services
Webmaster note In Part 2 of this two-part series, Lori answers the following questions:
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!
How can we determine the usability of an index?
I suggest that you review the Index Usability Questions on my Web site: http://www.indexingskills.com.
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).
