Eliminate Your Index Hassles: Don't Create One

Eliminate Your Index Hassles: Don't Create One

by Dick Miller

Radical idea! If you don't have an index in your document, you won't have any of the problems associated with creating an index, much less those associated with maintaining one. A document without an index is often seen as one of lesser quality. For example, Lori Lathrop, in "Intro to Indexing"(Intercom, February 1997, pp. 10-13) states:

"Developing a comprehensive index that contains entries for every useful nugget of information is at least as important as every other task involved in writing your manual. ... The index, after all, is the most important retrievability aid you can provide for your readers."

I'd suggest that these statements are only partly true, because of their focus on the index as the tool of choice by which readers access and retrieve information. In other circumstances, other access and retrievability tools may make more sense, and an index may require an effort disproportional to the benefit received by the readers.

"But how is the user to find what's in the document?" you say. Good question! I like to use a detailed Table of Contents.

An Indexless User Guide Is Not for Everyone
The suggestion I have applies only to relatively small, task-focused documents like User Guides for small applications. I doubt that it would be appropriate for large documents, where a detailed index is really needed. Also, this technique would work best for guides that are focused on task performance rather than conceptual information.

I create user documentation for custom software applications developed for use at the company site where I work. Sometimes other company sites will leverage them, but, for the most part, our user community is entirely at our site or, perhaps, on a business trip to another company site. The applications tend to be relatively small and specific. They are requested by the client organizations at the site, such as Procurement, Finance, Marketing, etc.

The number of users for these applications is usually small, ranging from ones and twos to dozens or, sometimes, hundreds. As such, we try to minimize the cost of developing the documentation, in order to keep per-user costs down.

These guides tend to be largely procedural, with very little conceptual information. Most of the users are very familiar with the business process driving creation of the software, and so need to understand only how to use this new tool to accomplish the same (or similar) job tasks. The guides are typically used when a user is new to the software or when s/he needs to use a feature for the first time in a long while. Once the basic use of the software has been learned, they don't need the guide for routine tasks. It serves as a reference for infrequent tasks, or those that are new to the user.

Think in Terms of User Jobs and Tasks
Typically, the software development team, through their requirements analysis, have a pretty good idea of the jobs and tasks that the software is expected to cover. In addition, since the user community resides on-site, it's easy to interview members of the target audience to clarify and provide detail on those jobs and tasks. I organize my user guides into major subsections similar to the following:

Introduction--A tiny bit of conceptual information, generally related to how the software helps them to do their jobs
Accessing the XYZ software--includes installation, security procedures, etc.
Using the XYZ software--herein lies the bulk of the guide's procedural information.
Glossary--largely application-specific terms and acronyms defined and described.

The "Using" and "Administration" sections are organized as much as possible in ways that makes sense to the job incumbent. These may include:

By date (do this on the first day of the month, that on the third day, etc.)
By sequence (do this, then do that)
By frequency of performance (daily tasks, then weekly, then monthly, etc.)
By criticality (if you don't do the first one right, don't bother worrying about the others)
or by any other way that makes sense to someone doing the job.

Please don't organize the manual according to where items are located in the software's menu structure. This may make sense for software developers, but users find it less than helpful in learning how the software helps them do their jobs.

Use Action Statements for Subsection Headings
The higher-level organizers mentioned earlier help users to locate the general area where they can find the information they need. You can use one or two levels of organization below to organize the task instructions. Each of these should be a verb-noun pair that describes a component of the task, similar to the following example:

Using the XYZ software
Retrieving part information
Specifying search criteria
Selecting a part number
Specifying a date range
Modifying part information
Selecting a part number
Modifying a part description
Modifying part vendor information

And so forth. Notice that some topics may be repeated ("Selecting a part number" in our example above). It's important to include the task information each place it occurs, so that users don't have to go flipping pages to find what they need. If the procedure is truly identical in several different contexts, you may want to consider pulling it and others like it out into a section at the beginning of the "Using the XYZ software" section, called "Common procedures."

Build the Table of Contents from the Section and Subsection Headings Most word processing software has a function that allows you to build a Table of Contents automatically from the headings of the sections and subsections. You need to make sure that each of the section and subsection headings is written in the appropriate style. In our example above, the appropriate style is noted in parentheses in the illustration below:

It's also a good idea to specify a style for the Table of Contents that shows the sections and subsections in a progressively indented manner, such as in the example above. This allows users to put the subtasks in context with the other subtasks and the tasks of which they are a part.

Teams are configured formally or informally, with lines of communications and decision-making varying from nonexistent or obscure to highly structured, almost to the point of brittle rigidity.

Summary
You don't need to create and maintain an index for a user guide if the application is relatively simple and task-oriented. A well-crafted Table of Contents can serve the purpose of helping users to locate information in the guide. This saves a considerable amount of documentation development time, effort, and money. This is an important consideration for documents and applications with a relatively small target audience.

Dick Miller has worked to help people understand and use complex systems for 35 years in a variety of positions in the public and private sectors and as an independent consultant. Currently he is at Hewlett-Packard in Vancouver, Wash., where he provides documentation and usability services for the Information Technology Department. He is a member of the Usability SIG, where he was the editor of their award-winning newsletter. In what free time he can find, he likes to play Dixieland trombone and tuba. Dick Miller can be reached at dick_miller@hp.com.