Indexing Guidelines for Use Guides Part 1

by Editor on January 23, 2014

Should you add an index to your user guide and if so what should you include? Both are worth considering if your user guide is more than twenty pages. Why twenty?

In general, if a document is relatively small, there is no need to include an index. And while there are exceptions, you can usually reserve indexes for larger documents. The questions then are:

  • What to index?
  • What level of information needs to be indexed?
  • What can be omitted?
  • How to index?

Put yourself in the user’s shoes. Why do they go to the index? It’s usually because they can’t find the information in the table of contents and don’t have time to scan the entire document. Also the same item may be in different places in the document.

Suggested terms to include are as follows:

  • Product names
  • Specifications
  • User Interface controls
  • Techniques to perform tasks
  • Materials
  • Conditions

Create a reference list

Read the document and as you can come across key words or terms relating to the subject matter, add these to the list. Later, you can decide what goes in or out. Notepad is a simple way to track these.

What level of information needs to be indexed?

As you record these words, note variations of the term, for example, if your document is about investing the terms CDS and Credit Default Swap may both need to be indexed.

Why?

Users search in different ways.

Some will type in CDS, others Credit Default Swap. Add both to the index and cross-reference the related keyword. Make sure to include possible synonyms or variations for each term. Note the page number where the terms occurs, and the context in which it is used.

Next, identify what information can be indexed and what should be excluded.

What can be omitted from the index?

After you have created your Reference List, you’ll get a feel for terms that come up repeatedly whereas others may only be referenced once and may not be index candidates.

In addition to this, the following can usually be excluded from the index:

  • Footnotes
  • Endnotes
  • Abstracts
  • Tables
  • Images
  • Appendices

Note: ignore words that are mentioned in passing and are not directly related to the core functionality.

What should be indexed?

  • Focus on those critical words (and phrases) that help the reader understand the subject matter.
  • Next, look at the verbs used in conjunction with these terms, for example, printing, deleting, merging etc that users are most likely to need. Develop your index around these words and phrase.
  • Words also known as

If necessary, include similar words that may also be used by reader, for example:

Web Content

Also known as: “E-Content”, “Online Content”, “Internet Content” and “Digital Content”

Index to Page Ratio?

If I have a 100 page document, how long should the index be?

Something to consider is that for every 100 pages, you should have about 5 pages of index entries. That means that 5% gets indexed. I’ve heard other indexers use a higher percentage.

It’s up to you. However, if you deliver less than this, maybe your index is too shallow.

Index cards photo courtesy of lisa eckstein

Difference Between User Guide and Getting Started Guides

January 16, 2014 Document Plan

In this tutorial we look at the difference between User Guide and Getting Started Guides? When should you create one instead of the other? What goes into the User Guide that doesn’t go into the Getting Started Guide and the other way round? Let’s take a look. User Guides: what to include? Are comprehensive. They [...]

Read the full article →

User Guides: How to describe System Crashes

January 9, 2014 Writing

When writing user guides you may need to describe how to application stopped working. The most common way to write this is to say that it crashed but it’s best to avoid this as it’s misleading, sometimes inaccurate, and sounds like jargon. So, what’s the best way to say that your application crashed without using [...]

Read the full article →

How to write your first user guide

September 30, 2011 Writing

When’s the last your read a user guide and thought, “Wow, that’s great!” User guides have a bad reputation. Instead of seeing them as something that helps get the job done, many feel that user guides (aka user manuals) makes things more different. So, how can we write a user guide that: Users want to [...]

Read the full article →