Index Essentials
An index helps users to find the information they need in the documentation that you write. A good index records every pertinent statement in the body of the text. The subject matter and purpose of each section in your book determine which statements are pertinent and which are peripheral. Deciding which statements are pertinent is a judgment call, and the task that causes most difficulty for writers. These guidelines help you to recognize and label statements for an index.
- 6.1.1. Topics to Index
- 6.1.2. How to Compose Index Entries
- 6.1.3. Index Navigation
6.1.1. Topics to Index
Consider the following points when you look for pertinent statements to index:
- A pertinent statement can be a single phrase, a sentence, a paragraph, or even several pages.
- Begin the search for pertinent statements in the first paragraph of the main body of your manual.
- Conclude your search for pertinent statements on the last page of the last appendix.
- Do not index the front matter.
- Indexing the glossary can provide a useful source of information for the user but is not essential, especially for manuals that appear in print as well as online.
Statements that refer to the following topics are often pertinent for an index:
- Definitions
- Restrictions
- Acronyms
- Commands
- Command qualifiers
- Routines
- Data structures
- Key functions
- Procedures and tasks
- Tips, notes, and cautions
- Examples, tables, and figures
6.1.2. How to Compose Index Entries
When you identify a pertinent statement, you need to flag the statement in a way that alerts the user to the information. This flag is the index entry. When you compose an index entry, you must first determine the topics that relate to the statement. These topics become the primary entries. Next, you must determine the nature of the information in the statement relating to each topic. These descriptions become the secondary entries.
- 6.1.2.1. Primary Entries
- 6.1.2.2. Subentries
6.1.2.1. Primary Entries
Make your primary entries precise, logical, and consistent with the terminology in the rest of the documentation set. Some tips:
-
Make your primary entries nouns or a noun phrase that a user might look for. For example:
Applications Noun. Starting applications Noun phrase. -
Do not use verbs or adjectives standing alone, because users are unlikely to search for these words.
-
Make sure that the term used for the primary entry appears on the page to which the index points.
6.1.2.2. Subentries
A subentry is a verb, phrase, or adjective that describes the nature of the information about a topic. You can also use nouns and noun phrases for subentries. For example:
- Applications
-
menu
starting from menu
starting from command line
See the http://developer.gnome.org/projects/gdp/handbook.html, Indexing for more examples of index subentries.
6.1.3. Index Navigation
You can use the following types of cross-references to help users to navigate the index:
- See
-
Use this cross-reference to point from a synonym to the term under which the user can find the index entries.
- See also
-
Use this cross-reference to point the user to topics that are related to the original entry.