Index this!

An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions.

In this post, I share my best advice about building an index. And I ask for your help and opinion on a couple of details.

To make your index entries helpful, anticipate user searches. Think of it as a parallel to online search results. When building an index, think primarily of what users might want to look up and find in your documentation.

To create an index, follow these three steps:

  1. Create index entries.
  2. Build the index.
  3. Clean up your index.

1. Create index entries

  1. Scroll through your entire document and search for words and phrases that you want to appear in the index. Select only occurrences with substantial descriptions, not just mere mentions.
  2. Create an index entry, depending on your help-authoring tool or other software. Edit the entry to avoid all unnecessary words, such as articles (“a” or “the”) and prepositions (“in” or “by”, etc.).

When creating index entries, consider these issues:

  • Redundant entries, where you have several entries for the same thing, may seem wasteful and confusing. However, if users are likely to search for the word “equity” in addition to “stocks”, consider using one of the terms to refer the reader to the other entry.
  • Cross-references between index entries is a suitable compromise between usability and completeness: Of course, it is an extra step for the reader to move from the entry “Equity: see Stocks” to the “Stocks” entry. On the other hand, it is much more difficult for writers to keep both entries “Equity” and “Stocks” complete and identical over time. Which do you prefer, as a reader and as a writer: Is it okay for readers to move to a second entry? Or should the page numbers be at each entry?
  • Nested entries can help you to structure your index and alert the user to hierarchies of concepts and functions. It also cleans up your index by avoiding redundant words. Don’t have more than two levels, however. What’s your experience: Are nested entries helpful or generally confusing to readers?

2. Build the index

At any time after creating your first index entries, create and preview your index, depending on your help-authoring tool or other software.

3. Clean up the index

After you have created all index entries, rebuild and update your index. Then review the existing index for inconsistencies and go back to the index marks in the text to correct the following issues:

  • Omit double entries of the same term, but with different spelling or singular and plural.
  • Break up index entries that list more than 5 target pages. Refine index entries, for example by creating additional second-level entries for separate tasks, such as “Setting up”, “Calculating”, etc.

Optimal length and scope of an index is the result of a compromise: Make your index as long as necessary to support readers to use your documentation quickly and efficiently. And make your index as short as possible to spare yourself unnecessary work and the reader confusion.

Whether your index is too long or too short is a matter of judgement. Put yourself into the reader’s shoes once more and review your index. You may find that your index is a little too short and missing some terms that users might also look up.

Read more

Good resources for building an index are these two web pages and three books:

Your turn

Please help me out by weighing in with your experiences and opinions to the questions above. Or feel free to tell me if  I forgot anything? How do you create an index for printed documentation? Should online help also have one, or is the search enough? Please leave a comment.

Advertisements

2 Responses

  1. We are single sourcing PDF guides and a help system from the same source topics. The topics contain index entries that will form a traditional index in the PDF output. In the help system, they perform two functions: 1) They act as keywords in the metadata. If a user’s search term is found in the topic’s keywords, it is ranked high in the search results. 2) They are offered as search suggestions. As the user types a search term, matching index terms are presented as suggestions. We don’t put the traditional index in the help system, however.

    • Thanks, Juliette, that’s a pretty interesting use case for index terms in online help. I’m currently working on an information model for online help that include metadata. I’ll see if I can map index terms to keywords somehow…

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this:
https://kaiweber.wordpress.com/2010/07/05/index-this/
kaiweber.wordpress.com
crawl=CC-MAIN-2017-30
122653
application/http; msgtype=response
sha1:G4CKM534ZGYIW3TSJXNG5JXCO7QFJC5N
<urn:uuid:8b058340-ab15-4da9-84c3-a793f7ca04bc>
2017-07-27T08:51:27Z
192.0.78.13
application/xhtml+xml
sha1:2OZFNRF7RWVSTXCHUCLJHI6GZABMZZDW
<urn:uuid:4d37451f-cb15-4484-aa91-b1d77ffe74ea>
https://kaiweber.wordpress.com/2010/07/05/index-this/
length
response
<urn:uuid:7228d80f-5083-4586-b093-22b822cbb66f>
robots: classic
hostname: ip-10-232-78-197.ec2.internal
software: Nutch 1.6 (CC)
isPartOf: CC-MAIN-2017-30
operator: Common Crawl Admin
description: Wide crawl of the web for July 2017
publisher: Common Crawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf