Creating Online Help (Part 2): Strategies and Implementation

Developing the Help Index

Whereas the table of contents in a Help system locates information conceptually, the index helps users find information through words or phrases associated with topics. Good indexes can be difficult to create and often not enough time is devoted to creating rich sets of index entries. Instead, only a few index entries are included, making the index relatively useless.

Indexing Concepts

To create a rich index, you need to make sure that each of your topics includes a variety of relevant index entries so that your users stand the best possible chance of finding the information they seek in your Help system. Strive to do better than simply create a single index entry per topic, otherwise users must be lucky enough to stumble upon that one entry to find the information. Instead, consider a range of terms that might occur to someone looking for a Help topic. Avoid farfetched entries, however. Do not clutter your index with entries that are unlikely to be used; use two or three relevant words instead.

Analyzing your audience is critical to producing a quality index. Understand what kinds of index entries your users will likely use to find the information they want. Create indexes around the level of sophistication and backgrounds of your users. For example, there is little value to using index entries that are far too technical for novice users. Terms such as uploading files may not mean as much to novices as transferring files. However, if you anticipate having more sophisticated users, consider using both terms.

Phrasing, Capitalization, and Punctuation Conventions

Many index entries are verb forms that express the verb-plus-object relationship. For these index entries, use gerunds (deleting files). Many other entries, of course, are simply noun phrases (overtype mode).

Although index entries may be singular or plural, you are advised to determine which one to use and then apply it to all your entries. Most Help authors choose the plural because it does not require the use of an article before the noun. Using plurals is not problematic when using gerund entries as plurals (deleting files). Other nouns are singular because they are concepts (alignment) or proper nouns (Truecode). In the case of interface elements, use the plural when there are more than one of them (toolbars); use the singular when there is only one (Ruler).

Lowercase most index entries but uppercase proper nouns or interface elements that are normally capitalized in documentation. These include commands (Save command) and interface objects such as Project toolbar or Date field. Use uppercase also for terms that are normally capitalized, such as ASCII.

Another good approach for formatting index entries is to use nouns for your first-level index words but use related verbs for your sublevel entries. The RoboHelp Help index capitalizes all first-level entries and lowercases most of its sublevel index entries, whereas Microsoft Internet Explorer Help lowercases most everything (see Figure 18).

Figure 18. Capitalizing each first-level entry but lowercasing most sublevel entries (RoboHelp HTML, left); lowercasing most of its index entries (Microsoft Internet Explorer, right)

Indexing Problems to Avoid

Creating a good index takes practice. Here are some common pitfalls to avoid:

• Unindexed entries: Make sure all topics have index entries linking them. Diversify those entries to make your index rich.
• Duplicate entries: Review all index entries to look for unintentional duplications and variations of the same words. For example, avoid creating an index that includes both date and dates as separate entries, as well as similar entries, such as adding record entries and adding records. They are practically the same.

• Inconsistent indexing of similar topics: Make sure to phrase index entries similarly. For example, suppose you have the following two topics with corresponding index entries associated with them:

  • Topic one: "Previewing a Form" has four index entries: previewing forms; forms, previewing; print previewing; zoom view

  • Topic two: "Previewing a Report" has three index entries: previewing reports; reports, previewing; print previewing

  In this example, "Previewing a Report" has no reference to zoom view at all, even though the topic also references it. The two topics are inconsistently indexed.

  Instead, create consistent index entries, as shown in Table 1.

  Table 1. Consistent Entries for Similar Index Topics

  Index Entries for Topic "Previewing a Form"	Index Entries for Topic "Previewing a Report "
  previewing     forms	previewing     reports
  print previewing	print previewing
  forms previewing	reports previewing
  zoom view     forms	zoom view     reports

Page 6 of 8

Previous Page

Next Page