Design Strategies

Considerations in Indexing Online Documents

by Lori Lathrop, 76620.456@compuserve.com

Printed indexes were the precursors to hypertext links. If you have good indexing skills, you can apply those skills to writing indexes for either printed books or online documents. Although locator systems are different in electronic media than in printed books, the basic principles of indexing apply to both online documents and back-of-the-book (b-o-b) indexes.

Most online indexes look very much like b-o-b indexes; however, because online information is not linear, the biggest difference is that hypertext links in online documents serve the same purpose as See and See also cross-references in b-o-b indexes. Another difference is that most indexes for online documents use just one or at the most, two levels of index entries--that is, main headings and subentries, but no sub-subentries.

What Is an Index?
An index is a detailed topic analysis of the text. In a sense, it is a highly condensed overview presented as a conceptual map that helps readers see the scope and content of the entire document and navigate through the information.

Indexing is an art and a unique style of writing in its own right; it is not a mechanical process. Not everyone has the ability to objectively and accurately analyze text and produce a conceptual map that enables readers to easily locate major concepts, topics, and definitions. However, any technical communicator can learn the basic concepts of indexing and learn to recognize the qualities of a good index with meaningful keywords.

A usable index should:

- Anticipate how readers will search for information
- Help readers retrieve needed information
- Reflect the terminology of the document
- Direct readers from terms that are not used to terms that are used
- Provide a topic analysis that reflects the contents of the document
- Show how various topics interrelate
- Group together information on a subject that is scattered in the document
- Discriminate between useful information on a subject and a passing mention
- Exclude irrelevant information that offers nothing significant to readers.

Keywords
Keywords (index entries) for online indexes are taken directly from the text. Users can then select the keyword, which appears highlighted on the screen, and be launched directly to the referenced text. This process is equivalent to using See references in printed indexes to direct readers to preferred terms or using See also references to direct readers to related information.

Assigning keywords only to terms that actually appear in the text is often a shortcoming in online indexes. In addition to creating keywords that reflect exact wording in the text, you should also create keywords for concepts when it is not possible to use the exact words or phrases in the text. Look for the essential concepts and present those concepts as clearly as possible. Also, you should include synonyms that readers are likely to think of, even if that synonym does not appear in the text.

Because online information is not linear, there are several differences in design when compared to printed documents. For example, a computer screen can display only about one-third as much (or less) as a printed page; therefore, online documents present information in modular "chunks" that contain more detail than a comparable amount of space in a printed text. Each "chunk" should be assigned at least one keyword that users are likely to look for when performing searches. In that respect, it is more important for the indexer to anticipate readers' needs in online documents.

Readability and ease of use are extremely important considerations in designing online documents. Because the resolution of information displayed on a computer screen is considerably less than the resolution of typeset documents, fatigue sets in more quickly when reading online documentation. Readers' attention spans are shorter when reading static displays. For that reason, the index is an invaluable retrieval tool in online documents.

As you analyze the document, be sure to create keywords for:

- Chapter headings
- Table and figure captions
- Examples and figures
- Definitions or new terms
- Acronyms or abbreviations
- Synonyms
- Main topics of paragraphs (or "chunks")
- Important concepts
- Warnings or restrictions
- Main tasks
- Main product features
- Screen names
- Field names
- Functions, commands, parameters
- Menu options

Seamless Links
Hypertext links that launch readers to related information must appear seamless, no matter how scattered the references are in the online document. Readers searching for information in an online document do not care about the actual "location" of that information; unlike searching for information in a printed book, they do not perceive a beginning, middle, and end in the document. Their only goal is to retrieve the information they want as quickly as possible. In that respect, there is very little difference between what users want from online indexes and what they want from printed indexes.

Tip. Use your index as a usability tool. If you notice that information on a particular topic is scattered throughout the text, take that as your cue to evaluate the organization of the document.

Tips for Generating Keywords
The following tips apply to indexing both b-o-b indexes and indexes for online documents:

- Create index entries in noun form, preferably singular. Some examples of entries that would be inappropriate in singular form are: messages, printers, screens, graphics, and commands.
- Pay attention to terms that are proper nouns and also to terms that are case sensitive, such as some statements, commands, and parameters. Index them exactly as they appear in the text.
- Arrange all entries alphabetically. In an effort to keep related topics together, you may be tempted to devise some other arrangement, but ... don't do it!
- Be concise. Eliminate unnecessary entries if they can be consolidated into a more general entry. Also, be sure that subentries "read back" properly to primary entries.
- If a primary entry (main heading) has only one subentry, eliminate the subentry and include the page reference with the primary entry.
- If keywords have more than three links (or page references), it may be a good idea to create subentries that would be more helpful to readers.
- Do not use unnecessary articles and prepositions.
- Use prepositions only in subentries and only when the entry would be unclear or confusing without them.
- Ignore articles and prepositions when sorting alphabetically.
- Do not begin entries with articles (a, an, the) or with conjunctions (and, or).
- Consider ways to expand the index and improve readability by (a) using subentries as primary entries, (b) creating additional entries by rearranging the word order of existing entries, and (c) including synonyms for important terms and concepts.
- Use capitalization, punctuation, and other stylistic conventions consistently.
- Qualify commands, fields, parameters, and other special names; for example: merge command, SETUPFW program, DIF (data interchange format) files.
- Consider methods of vocabulary control to avoid "variations on a theme" (such as NewPage command, newpage command, and new page command).

Indexing Pitfalls
Readers are more easily frustrated when searching an online index because they do not have the advantage of the spatial orientation they're familiar with in printed books. When readers are unable to find index entries for information in a printed book, they often look for other retrieval aids, such as the table of contents or headers and footers, and they inevitably resort to "eye-balling" the text in hopes of stumbling upon the information they need. However, those same readers are likely to be considerably more frustrated if an online index fails to direct them to the information they want; the sheer size of the online document may cause readers to think that scanning the document for the information they want 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, they are likely to call a Hot Line 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 Hot Lines 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.

Lori's experience includes more than 16 years as a technical writer, editor, and professional indexer. She provides indexing services for corporate clients and publishing houses throughout the U.S. and Canada, and she delivers her two-day workshop, Indexing Skills Workshop for Technical Communicators, for corporate clients and writers' organizations. Lori’s book, An Indexer's Guide to the Internet, is available from the ASI, PO. Box 386, Port Aransas, TX 78373 / phone. 512-749-4052 / fax 512-749-6334. The price is $10 for ASI members and $15 for nonmembers.