Return Home

The Art of Indexing
Establish relationships and then divide
By Susan Self

Author bio

Susan took a one-day STC indexing workshop with Lori Lathrop and Richard Evans in 1994 and then organized what she learned and practiced into a method. Click here for a short paper on the indexing method.

Click here for slides of an in-house workshop Susan gave on the indexing method.

Click here for slides of a presentation on indexing with FrameMaker that Susan gave to a local FrameMaker users group.

In making an index, you can find it easy and gratifying to add the entry for that odd but important bit of information that you know readers will want to find and that would otherwise be lost in the sea of text, such as "hardware dongle." Such cut-and-dried entries are the Norwegian bachelors that keep quietly to themselves and don't have a lot of relationships with other topics.

At the opposite extreme are the overly gregarious topics that would gather nearly half the book under their wing in column after column of related entries if you don't set a limit somewhere, usually at the length of a column.

The art of indexing can thus be considered the art of establishing relationships among topics in small- to moderately-sized groups. It cannot be done entirely deductively, laid out in a plan, from the start of the process. You usually have to start making your major group headings and see how many topics fit into them before you realize that they have become too large and unwieldy. After you have united all of these dispersed relatives under one heading, you then have to start dividing them into special-interest groups.

Special Interest Groups

As an example, in a chapter on Log Session Manager, the log session group covered much of the chapter and had to be broken into special interest groups with their own members: log session, log session creation, log session list, log session operations, diagnostic log session, and performance log session. The "godfather" entry, "log session," had a "see also" reference to the related special-interest groups to keep the flock loosely together and so that readers would know to look for the other groupings.

In addition to the entries for log session, as an object with properties and operations, were the entries for the software tools used to create and manage the log session objects, the Log Session Wizard and the Log Session Manager. Because a log-session operations group had already been defined, the entries for the tools were limited mainly to the significant parts and features of the tools, not the operations that they performed related to log sessions.

In this approach, the object categories, rather than the tool categories, contain the operations that can be performed on the objects. This could be called object oriented indexing as opposed to tool oriented indexing.

Small Towns and Neighborhoods

A chapter on the Log Session Manager is like a small town where everybody is related to or knows everybody else. Sometimes it is tempting to assume that these relationships will still be recognized in the context of the whole book, which is like a big city with a heterogeneous complex of neighborhoods. An innocent entry such as "selecting a template" can get lost outside its context if configuration and data analysis tools described in the book also have templates that can be selected. For this reason, lower level topics tend to huddle under major entries in their local neighborhoods and don't tend to mix with other topics where their meaning might be ambiguous or misunderstood.

A good command of the territory covered in the neighborhoods is essential before you start to index so that you can assess which entries can stand on their own as primary entries and which have to be protected within a specific context. Generating a separate index for a chapter can help you to spot weak primary entries in a chapter before they get lost in the complete general index for the book.

Orphans

In contrast to small towns and neighborhoods in chapters brought together in a book are the orphaned data items in lists and tables in reference manuals. Without the guidance of a discussion that explicitly links the items, it may seem pointless to try to fit them into meaningful entries. Yet, in some situations, collecting these together under umbrella topics can prove extremely useful. The index becomes the only venue for this family reunion of dispersed relatives.

As an example, one chapter describes data that counts the number of dropped calls that occurred for mobile phone users. Another chapter describes data that captures signaling messages that occur before dropped calls. Still other pieces of data scattered throughout the manual describe separate problems that can be contributing causes of dropped calls. The topic "dropped calls" can group all of these types of data together in one place. The researcher can reference the topic to learn how to find out if the system has a high rate of dropped calls, what the possible causes might be, and how to capture messages to analyze the problem and solve it. "Everything in the book related to dropped calls is right here!"

Celebrities and Commoners

Indexes for reference manuals often have lists of entries that insist on being called by their proper names and prefer not to mingle in groupings with the "common" nouns. If you have enough of these prima donnas, the harmony of the index can be greatly improved if you create a separate "celebrity" index for them.

Focused indexes are quite useful for long lists of items looked up frequently for reference, such as names of metrics, alarms, or error messages generated by a system. You need a large enough class of items to warrant a separate colony, however, or the benefit is offset by the risk that readers won't find the separate index in the first place.

As a way to cover that risk, and to help readers who can't remember a celebrity's name, you can force the proper names under topics in the subject index anyhow, however much they may resist. A separate index does not save space then, but it can save time for the reader armed with a name. Who wouldn't rather search a 4-page index than a 20-page index?

However, to meet the family of the celebrity, you need to locate its neighborhood in the longer subject index. In the process, you may discover some other, surprising celebrities and commoners it has as friends. That's the beauty of an index: it brings together all sorts of items in unexpected relationships.