Chapter 10. Indexes
An index is an alphabetical list that provides multiple entry points to information. In addition to being a primary retrievability aid in online information, books, and PDF files, a good index can improve search results within an information center. Nevertheless, because an index reflects an analysis of the relationships among topics, it is more discriminating than search; an index can help users locate a specific piece of information faster than a long list of search results can.
Levels of index entries
An index entry can have up to three levels. The following example shows the notation that is used to refer to the levels:
Locators lead users from index entries to the location of information. In information centers and other online forms of information, locators are links. In hardcopy information, locators are page numbers. In PDF files, which can be viewed online or printed, locators are both links and page numbers.
Integration and reuse
In information centers, the index entries in each plug-in are combined to create an index for all of the topics in the information center. You display this index, which is referred to as a master index, by clicking the index tab. Because the index entries of individual authors are consolidated with those of other authors, the master index must be evaluated and edited as a whole to make all the entries work together consistently and to address redundant or overlapping entries. When writers add new entries to an individual index, they should look at the master index to make sure that their new entries are consistent with the existing entries.
The same index entries might be reused in different forms of output: a technical publication, a single PDF file, and an information center for one or more components or products. In some situations, you might need to tailor your entries for different uses (for example by adding a product or environment identifier) to help users of an integrated solution understand what they can find in the topic.
Size and sorting
For information center topics, include at least two index entries per topic. For longer task and concept topics, include up to eight index entries per topic. Long reference topics might require more entries.
For PDF books or printed information, include approximately one entry for every 100 words of text, or six entries for each 8.5-inch x 11-inch page of text. This standard results in approximately one double-column page of index entries for every 20 pages of body text, or one three-column page of index entries for every 30 pages of body text.
Most authoring tools sort index entries automatically. If you must sort index entries manually, see “Index sorting” on page 270.
Index content
Create index entries for all significant content. The following list describes the types of content that should be indexed and types of content that do not require index entries.
Concept topics
Index the user goals that are related to the information in a concept topic. Index the subjects, not just the topic title, and any information that is important to users and not explained more fully elsewhere.
Task topics
Index the goal that users accomplish by doing the task, and the objects or artifacts that are affected by, created by, or used to do the task.
Reference topics
Index as main entries all syntactic elements that users might look up. Label each element to specify its type, for example command or function. Index the parent element, such as a command, instead of its child element, such as a command option. Index both the name of an element and its category, for example, commands, configuration parameters, functions, or monitor elements.
API reference topics
For generated API documentation (such as Javadoc information), in the container topic, index only the base package, not the individual interfaces, methods, classes, or functions. Think of how users can find the package if they do not know the name, such as by looking up a goal or the object that an API extends.
For authored API topics in general, index only the API name and the goal; index specific interfaces, methods, classes, or functions only by exception.
Container topics
Index the high-level task, concept, reference element type, or tutorial that a container topic is focused on. For container topics that contain a small amount of significant content, create a main entry for the subject of the container topic and a secondary entry of overview. Thoroughly index the child topics that are linked to from the container topic.
Scenarios, samples, examples, and tutorials
Index examples, samples, and scenarios by action and concept. Under the subject, use the information type (example, sample, or scenario) as a subentry. For tutorials, put index entries in the main topic with a subentry of tutorial. If useful stand-alone information exists in specific lessons, index that information under the task, concept, tool, or component.
Legal and accessibility information
Index all keyboard shortcuts and other accessibility features under both the feature name and accessibility.
Legal information
Index the notices under a main entry of legal notices with a subentry for the product. Do not index trademark notices.
Files
Index file names under the file types, not the file extensions. For main entries for specific file names, use the complete file name followed by the word file. Index archive files under what they are used for.
Graphics and tables
Index the main subject that is being presented in a graphic or table only if that subject is unique to the topic. For example, concept topics that describe the architecture of a product often include a graphic depiction of that architecture. A separate index entry typically is not needed for the graphic because index entries that describe the overall subject of the topic apply to the graphic as well.
Index UI elements, such as fields, panes, check boxes, buttons, and views only if they are something that you know users must look up. If your team creates documentation for wizards, index them under the tasks that the wizards help users perform. Index context-sensitive help topics when they are the primary documentation for a product. Do not index context-sensitive help for UI elements.
Product overviews
Index only substantial and unique introductory content that is not explained more fully elsewhere.
Product and component names
Generally, do not create main entries for product names. In rare cases where you do need to create main entries for product names, such as when an optional, separately orderable product is mentioned, include only a few important subentries. Index a component under its name and also under the functionality it provides or the user goal that is associated with the component.
Glossary terms
Do not create index entries for the glossary. Index a term in a topic only when that topic provides substantial information about the term.
Index structure
When structuring index entries, consider such things as the number of levels, position and number of locators, number of subentries, opportunities for cross-posting, and the use of See references.
Levels
• Create up to three levels in an index by using main entries (i1s) and subentries (i2s and i3s). Use i2s to help readers distinguish between topics that share an i1, and use i3s to help readers distinguish between topics that share an i2.
• Do not use i4s or lower-level entries. Instead, add differentiating information in parentheses at the ends of the i3s, or restructure your entries.
• Do not use commas unless they are part of a product name. Instead of using a comma to separate terms in an entry, create an entry and a lower-level entry, and consider cross-posting.
Locators
• In hardcopy books and periodicals, the locators that lead users from index entries to the information are page numbers. You can use page ranges (such as 22–25) if the text that is relevant to the indexed term covers more than one page. However, if text that is relevant to the term is scattered rather than continuous, index each reference separately.
• In online information, the locators that lead users from index entries to the information are links. If two or more topics share the same HTML or XML index entry, the title of each topic automatically acts as a subentry to help users decide which topic to look at first.
• Ensure that only the lowest level of an entry has a locator. If an entry has both an i1 and an i2, only the i2 can have a locator; if an entry has an i1, i2, and i3, only the i3 can have a locator. If you are writing documentation that will be combined with documentation from other writers, consider the entries that the other writers are using or might use. Unless you are sure that no one else has used or will use a particular i1, create an i2 for that i1. Similarly, unless you are sure that no one else has used or will use a particular i2, create an i3 for that i2.
In the following examples, the locators are page numbers.
• Have no more than three locators at the lowest level for any entry. Instead of adding more locators, provide more specific entries.
Number of subentries
• Before placing more than one i2 from a topic under an i1, try to use a more generic i2. Similarly, before placing more than one i3 from a topic under an i2, try to use a more generic i3. Consider using more detailed entries as i1s.
• Instead of providing a long list of i2s from different topics under one i1, consider creating more general i2s and adding i3s under those i2s.
• Create an i1 for a noun phrase only if it is often used by your readers or is defined in the glossary (for example, XML schemas or log streams). Otherwise, break the noun phrase into a more general i1 with an i2. If you think users might look for the multiword term under the general i1, use a See reference under that i1.
• In general, avoid having a single i3 under an i2 in the finished index. In this case, the i3 does not help the user to distinguish between topics; the i2 provides enough information, and the i3 forces the user to read an additional entry. However, optimizing your index entries for information centers can result in single i3 entries when you use the same index entries in a book, which is acceptable.
• Avoid having more than two subentries for the same topic under a particular higher-level entry.
Cross-posting
• When appropriate, create multiple entries for a specific piece of information because users use different lookup strategies. Consider using the following approaches:
• Invert the entries. Use the subject of an i1 as the subject of an i2, and use the subject of an i2 as the subject of an i1. Use a corresponding approach for i2s and i3s. For example, for a task topic, create an i1 for the action that is being performed and an i2 for the object that is affected by the action. In addition, create an i1 for the object and an i2 for the action.
• If an entry is a multiword term, consider creating additional entries in which nouns are i1s and adjectives are i2s (or i2s are nouns and i3s are adjectives) if doing so would not create an unnatural break.
• Index common, standard synonyms that a reader might use to look up information. Consider using a See reference to point from nonpreferred term to a preferred synonym.
• Create multiple entries for a specific piece of information even when those entries are close together in the English index. Because of differences in word order and parts of speech, in other languages the terms might not be near each other.
See and See also references
• Use a See reference to point from a nonpreferred term to a preferred synonym. Examples of nonpreferred terms are as follows:
• Obsolete names or terms
• Jargon
• Terms used by competitors’ products
• Industry synonyms
• Spelled-out forms of uncommon abbreviations
See references can help users learn the terminology of a product. They can also simplify the process of indexing by reducing the number of terms that you must index in detail. In an online index, clicking the See reference takes the user to the preferred synonym.
• Provide subentries only under the entry for the preferred term of a See reference pair.
• Do not use See also references in product information that might be combined with other product information, such as information center content, because different writers might create them inconsistently. Instead, use related links within topics to direct users to content that otherwise might have been addressed by See also entries. See also entries are permitted in stand-alone information, such as books or technical articles.
Other considerations
• Use i1s to refer to general categories of syntactic elements that users might look for, such as functions, commands, or configuration parameters. To reduce index bulk when you have a large number of the same type of syntactic element, instead of creating an i2 for each syntactic element, consider creating an i2 of list in a container topic that has links to child topics about each element.
• Do not repeat the wording of an i1 entry in an i2 entry or the wording of an i2 entry in an i3 entry.
Index entries
When you create index entries, consider capitalization and grammar rules, rules for indexing abbreviations, and rules that address terminology issues.
• For main entries (i1s), use nouns or noun phrases, even for processes or actions. For example, use installation, not installing; use migration, not migrating; and use search function, not searching. If no logical noun exists, use a specific and meaningful gerund, such as troubleshooting, loading, coding, or revoking. Do not use adjectives as main entries.
• Always use the plural form of a noun unless the subject is normally singular. For example, use databases, not database; use security, not securities; and use Control Center, not Control Centers.
• Make subentries (i2s and i3s) as specific and concise as possible. You can use nouns, gerunds, or adjectives. Use gerunds to indicate actions. Avoid overly common or nonspecific gerunds, such as using, working with, specifying, and learning about.
• Because writers often use different gerunds to mean the same thing, consider maintaining two lists of recommended gerunds to increase consistency across your library: a list of gerunds that can be used as i1s, and a list of gerunds that can be used as i2s and i3s. For example, different writers who work on the same library might use the synonyms creating, adding, developing, and building interchangeably. By identifying which gerunds are preferred, you can avoid inconsistency in the index.
If you use multiple gerunds synonymously, consider picking only one as the primary gerund, and use See references to point from the synonyms to the primary gerund.
• Do not use an adjective as the only word in an i1 where a noun is an i2.
• Place key words first.
• Capitalize proper nouns only, such as product names, trademarks, operating system names, and some user interface element names. Match the capitalization of the names of syntactic elements, such as API elements or command names (for example getCode method or runDatabase command).
• Do not use prepositions at the beginning of any entry because of their effect on alphabetization. In rare instances, you can use a preposition after the beginning of a subentry to clarify it. Avoid articles altogether, and remove any other extraneous words. Create subentries that are only as long as needed for clarity.
• Break entries that contain and in two so that both entries can be found alphabetically. For example, do not create an entry for administering and configuring. Create one entry for administering and another entry for configuring.
• For standard or common industry abbreviations that are significantly better known than the spelled-out forms and are unambiguous, index only the abbreviations. Examples are AIX, CORBA, HTML, SQL, PDF, XML, TCP/IP, and UNIX.
For other abbreviations, index only the abbreviation as an i1 and use a See reference to point from the spelled-out form to the abbreviation. This approach supports search and ease of maintenance.
• Use forward slashes only for well-established terms, such as I/O and read/write.
• When an index entry begins with a symbol, index it both with and without the symbol.
• Do not use bold or italic font for index terms.
Prohibited words
Avoid using the following words in index entries. Note that this list is not definitive. When you create an index entry, always use the most precise term that is available.
• about (never index “About this book”)
• appendix (index the contents of the appendix)
• caveats (too general)
• concepts (avoid the word; instead, create index entries for concepts)
• considerations (too general)
• definition (use details or overview)
• glossary (but index terms that are in the glossary where they are defined or discussed in topics)
• introduction (use overview as a subentry only)
• supertask (use overview)
• using (too general)
• working with (too general)
Index sorting
Most authoring tools sort index entries automatically according to a predefined setting. However, the use of certain documentation formats might require you to manually sort index entries.
If you must manually sort an index, follow these guidelines. Note that the alphabetization method for sorting index entries differs from the method for sorting glossary entries.
• Arrange entries in the following order:
1. Punctuation marks and special characters, sorted in ASCII sequence:
(space or null) ! 0 # $ % & ’ ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` } | { ~ ¢ > ≤ ÷ °
2. Numeric entries, sorted in ascending order
3. Alphabetic entries, sorted by word
• Alphabetize entries word by word; that is, treat words that are separated by spaces or commas as two words, and stop alphabetizing at the end of a word. If the first word of two or more entries is the same, the first letter of the second word determines the alphabetical order. If the first two words of two or more entries are the same, the first letter of the third word determines the alphabetical order, and so on.
Treat words that are joined by a hyphen or a forward slash as though they are two words that are separated by a space.
• Arrange abbreviations in alphabetical order as they are written, not as they are spelled out.
• Arrange Roman numerals in numeric order, not alphabetical order.