Online indexes should look similar to print indexes: they should have two levels with indented subentries. Many of the same conceptual guidelines for print indexes apply to online indexes.
The keyword is the term that a user associates with a specific task or set of information. The user types a keyword in the Find or Index box to locate specific information in a document. A keyword can lead to a single topic or to many related topics.
When deciding what keywords to list, consider these categories:
Terms for a novice user of your product
Terms for an advanced user of your product
Common synonyms for words in the topics
Words that describe the topic generally
Words that describe the topic specifically
Words commonly used in related products
Look specifically at the following elements of your document for potential keywords when you develop your index:
Sort HTML Help indexes in the same way as print indexes. You cannot manually sort the search keywords, so the order follows the ASCII sort order. Special characters appear first, then numbers, and then alphabetical entries. See also print indexes.
Follow most of the same general style guidelines as those used for printed indexes:
Use gerunds (the -ing form) rather than infinitives (the to form) or the present tense of verbs for task-oriented entries, unless they are unsuitable, as they may be for languages, systems, or localized versions. Consult with your team when making this decision.
Do not use generic gerunds that users are unlikely to look up, such as using, changing, creating, getting, making, and doing, unless you have no other choice.
Use plural for nouns unless it is inappropriate. This applies to both single keywords (bookmarks, not bookmark) and keyword phrases (copying files, not copying a file).
Do not use the articles a, an, and the, and avoid prepositions at the beginning of a keyword.
Keep keywords as short as practicable for clarity.
Use synonyms liberally, especially terms that are used in competitors’ products or terms that some users are likely to know. For example, list both option and radio button. Provide a cross-reference to the term that you are actually using.
For acronyms and abbreviations, list both the spelled-out phrase followed by the acronym or abbreviation in parentheses and the acronym or abbreviation followed by the spelled-out version. For example, list terminate-and-stay-resident (TSR) and TSR (terminate-and-stay-resident). If appropriate, provide a cross-reference at the less frequently used entry.
Use lowercase for all keywords and index terms unless the term is a proper noun or is case-sensitive, and therefore capitalized.
Microsoft style
clearing tab stops
clip art
Close command
modems
dialing a connection manually
setting up
troubleshooting
Some content will be shared among products. Single-sourcing, such as using the same file for both the Help topic about copying and a book chapter about copying, may extend across products instead of just occurring within a single product. Standardizing index entries across such products will simplify content reuse, and it will provide users with a consistent and predictable way of finding such information.
Topics, particularly those for technical support services and accessibility, should have standard keywords. For example, the technical support topic must include the following keywords:
assistance, customer
customer assistance
help
technical support
phone support
product support
support services
telephone support
troubleshooting
Help systems today can present a single index for multiple Help files. The keywords from the separate Help files are merged as if the main contents file specifies each Help file. If such a Help system contains an optional component that the user does not install, those keywords will not show up in the index but will be added to the index if the user installs the component later.
A merged set of keywords can be very helpful for users. However, it is essential that the keywords fit together appropriately. For example, if the main Help file uses the phrase exiting programs, then all Help files in the project should use this phrase rather than just exiting. Otherwise, when the keywords from multiple files are merged, the user will see two entries, “exiting” and “exiting programs.”
Do not use cross-references in online indexes unless you have no other choice. They are more difficult to handle in keyword lists than in print indexes.
Because each keyword must be linked to at least one Help topic, a cross-reference keyword has to jump somewhere, perhaps to an overview, or “main,” topic. It is often difficult to determine which topic that should be.
Also, cross-references (See and See also) are limited to normal keywords that jump directly to the topic that contains the K (keyword) footnote with that keyword. The cross-reference does not jump to another location in the index.
Instead of a cross-reference, duplicate all the subentries under both of the main keywords. For example, list all topics for “cursor” under “insertion point (cursor)” as well.
If you must include a cross-reference to other topics, you will want to force it to the top of the list of subentries. Talk to your indexer about how to do this.