Indexing Technical Manuals

[Chuck Banks <chuck -at- ASL -dot- DL -dot- NEC -dot- COM>]

In the January 1993 issue of the STC newsletter INTERCOM, an article
by Gene Curry appeared entitled _Indexing_From_the_Desktop_--_One_
Writer's_Method.  In his article, Gene Curry makes the following
statement:

"Who Should Index?
The author is the best person to do
the indexing, not an independent
third party or a professional indexer.
The author should know the readers,
anticipate their special needs, and
make sure every important
statement in his or her work is
indexed and easy to locate.  Just
as doing your own table of
contents helps you discover the
organizational weaknesses and
inconsistencies of your subject,
creating your own index helps you
discover missing and redundant
coverage.  Wouldn't you rather find
these flaws and fix them before your
reader (or your editor) sees them?"

Recent experience has shown me that I am not the best person
to do the indexing.  I don't have the knowledge or the skills
required to build a useful index.  However, I am trying to
acquire the necessary knowledge and skills.

Nancy Mulvany wrote a rebutal letter that, IMHO, states the
case for professional indexers better than I can.  Her letter
appears here with her permission:

February 16, 1993

Clark Mulligan
Editor, INTERCOM
Society for Technical Communications
901 N. Stuart St., Suite 904
Arlington, VA  22203-1854

Dear Mr. Mulligan,

I found the article, "Indexing From the Desktop--One Writer's
Method," in the January 1993 issue of INTERCOM to be quite
disappointing.  While there are an amazing number of matters to
take issue with in this short, 2-page article, first I will focus
my attention on one statement: "The author is the best person to
do the indexing, not an independent third party or a professional
indexer." This is akin to saying that "The programmer is the best
person to write the manual, not an independent third party or a
professional writer. The programmer should know the users,
anticipate their special needs..."

An unstated premise of this article is that any writer can write
an index. Unfortunately this premise is accepted throughout the
industry as we see that indexing one's manual is often part of
the job description of a technical writer. It is fair to assume
that the vast majority of indexes for computer documentation are
indeed written by the authors of the documentation.

It is no wonder that in a recent PC Computing poll (April 1992,
pp. 212-214), users of computer documentation rated the printed
index as the most important component of the package. As a rule,
readers do not notice good indexes because they are in and out of
them quickly; they find what they want and return to the text. On
the other hand, bad indexes are a quagmire not soon forgotten.
The results of the PC Computing poll are not an indication of
excellence in technical indexing, but rather a commentary on the
dismal state of the indexes in many computer manuals. Just think
of the countless hours wasted by users who cannot locate
information that is in documentation because of poor indexes.
Talk to any manager of a technical support department and you
will find that the support staff spends too much time reiterating
information present in the documentation. Think of the time (and
therefore, money) that would be saved if users truly had thorough
and accurate access to the information provided in product
documentation. The highly structured, authored subject index is
one of the most efficient and oldest information retrieval tools.

Nowhere in the article is training in indexing mentioned. I am
surprised that both the author and the editor of the article
found no problems with some of the sample index entries used. For
example, on page 4 the "Screens" entry is not in alphabetic order
and the sub-subentries, all with same page reference, under
"Account Setup screen" indicate improper structure. Alphabetizing
principles and the internal structure of entries are topics
covered in any basic indexing course. While reference is made to
The Chicago Manual of Style, the author fails to mention that the
vast majority of index modules in document processing software
cannot produce an index that conforms to the requirements of the
Manual of Style. This fact has been well documented in the
professional indexing literature.

In the article we are told that "Style means to structure your
index so each index item has the same grammatical form."
Hopefully it is apparent to most of your readers that index style
involves much more than "grammatical form." This should be
obvious since no less than 46 pages are devoted to the index
style requirements of the University of Chicago Press in Chapter
18 of the 13th edition of The Chicago Manual of Style; the IBM
Corporation's indexing style guide is 68 pages long; the current
draft revision of the American National Standard Guidelines for
Indexes in Information Retrieval (ANSI/NISO Z39.4-199x) is 64
pages long. These publications address index style in depth and
cover much more than "grammatical form."

Throughout the industry we now have plenty of examples of indexes
written by writers who lack indexing training and experience. It
is unfair to expect technical writers to produce adequate indexes
when they have no training in this area. It is a disservice to
writers, indexers, and documentation end users for Curry to
dismiss the services of professional indexers.

The voluminous amount of end-user computer documentation
published today has been a boon to the indexing profession. I
dare say that no other segment of the American publishing
industry has contributed as significantly to a heightened
awareness of the special skills of the professional indexer. I
hope that future articles about indexing published by the Society
for Technical Communication will present a more informed and
professional perspective than did your January 1993 INTERCOM
article.

Sincerely,

Nancy Mulvany
Past President, American Society of Indexers
Owner, Bayside Indexing Services


====================================

--
__        ________     ______
|\\   |  ||          //              Chuck Banks
| \\  |  ||_______  ||               Senior Technical Writer
|  \\ |  ||         ||               NEC America, Inc.
|   \\|   \\______   \\______        E-Mail:      chuck -at- asl -dot- dl -dot- nec -dot- com
America, Incorporated                CompuServe:  72520,411