# Indexing Your Documentation

This chapter provides you with tips that can help you to effectively index your documentation.

## 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.

### 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

### 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.

#### 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.

#### 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 GNOME Handbook of Writing Software Documentation, Indexing for more examples of index subentries.

### 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.

## How to Evaluate Your Index

When you create an index for a manual, you need to check the index for the following attributes:

- Balance and structure

- Clarity and consistency

### Balance and Structure

Check the index for the following common problems:

Overloaded primary entries

  If you find that a small number of primary entries in your index have a large number of subentries, try to find other labels for some of the subentries. Try to keep the number of subentries to a useful level.

Inadequate subentry labels

  If your subentry labels are too cryptic, for example just page numbers, then the reader does not have enough pointers to decide where to go in the book for the required information.

Unbalanced entries across the book

  If one or two chapters in the book are heavily represented in the index, then you need to look at the indexing frequency in the other chapters. Also, you might want to look at the overall information design structure of your book, to see if you really need those other chapters.

### Clarity and Consistency

To check the index for clarity and consistency, perform the following actions:

Ensure that all primary entries are nouns

  Look through your index for primary entries that are verbs and adjectives. Replace the verbs and adjectives with nouns or noun phrases.

Clarify the relationship between primary entries and subentries

  Make sure that the subentries bear a meaningful relationship to the primary entries.

Correlate primary entries and subentries

  Make sure that related subentries are all gathered together under the same primary entries.

## When to Index GNOME Documentation

When you want to index a manual, you need to consider the type of documentation:

Online Help

  As Scrollkeeper is still a product in development, the use of indexing is not yet clear. Until the situation clarifies, you only need to put a single index entry into each online Help manual to create a primary entry for the application name. The template for the online Help manuals provides an example of where to create the index entry in the online Help manual. When the role and function of Scrollkeeper becomes clearer, writers can apply more of the indexing principles outlined in this chapter.

  You can find out more about the templates in the GNOME Handbook for Writing Software Documentation.

Printed manuals

  Apply the indexing principles outlined in this chapter to printed manuals.