TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Indexing information From:Mike Beyries <beyries -at- CSISDN -dot- COM> Date:Wed, 9 Feb 1994 12:39:42 PST
LaVonna Funkhouser asks a few questions about index[es/ing/ers]. I think
this is an appropriate, important, and useful topic -- so I offer the
following thoughts. FYI, I am a practicing (practice, practice, ... )
tech writer with 12 years experience in small-, medium- and large-sized
computer products companies.
I think indexes are very important for any "type" of technical documentation.
Even tutorials and user guides need this kind of user-entry vehicle. In
the books that I write and those I review for others, my rule of thumb
(well, it's not a golden rule as in LaVonna's item 4, but close) is
that I like the index pages to represent 5 - 10% of the pages in the book.
That may seem like a lot, but I make allowances when the index has
more columns or smaller type than the body.
Now, to get a suitable index for book -- that's no mean trick! If you're
stuck doing it yourself [and I usually am :-) ] you might consider using
the following technique/s:
1. pick out important nouns and gerunds in subsection titles. they should
be in the index.
2. look for terms defined or explained in the text and make *sure* that
the defining occurence is indexed.
3. consider indexing the key phrase or term in the title of each table
4. ask yourself, and others who may respond, what synonyms for the items
already there (e.g., those from items 1 - 3 above) could your readers
use. remember, your golden words are not the only ones about this topic!
5. ask your reviewers, particularly those unfamiliar with the work to
suggest index items. an easy way for them to do this is to use a high-
light pen on the text as they read it. [I've had real success with
this when used on a marketing or tech support reviewer at the
next-to-last review cycle!]
6. if you're really determined to get a good index, it has to be a big one.
determined writers, even those who're tired of seeing their own words
for the leventy-hundredth time, can page through the book looking for a
(new) index entry in each paragraph. Just ask yourself, "what is this
paragraph about?" Notice that it must have a topic (if not a *real*
topic sentence), since you 'chunked' it as a paragraph! This technique
cna yield lots of index entries; it's best used in a quiet room where
you can escape interruption, and could be used on someone else's book
7. Of course, if you can get a professional indexer, editor, or peer-review
writer to help you (as in number 6), you'll get a wider perspective on
8. After building as big an index as you can -- using these or other
techniques, you need to make it a little smaller by looking closely at
multiple references (e.g., if that term is indexed on p. 12 it may
not also need to be indexed on p. 13), by standardizing (parallelizing?)
the phrasing of comparable entries, by structuring/using index levels
(for hierarchical entries such as 'data call, sending' and 'data call,
receiving'), etc. I guess my admonition to make it "smaller" is really
a suggestion to "tighten it up"! :-)
Well, this has been my pragmatic approach to indexes. I try to keep in
mind that most of the books I write will *not* be read cover-to-cover, and
so readers must depend upon a logical organization (revealed in the Table
of Contents) and a suitably large list of topics (in the Index) to find
what they need or want. BTW -- troubleshooting topics should be *really*
heavily indexed; people in enough trouble to look at the manual are not
in a forgiving frame of mind!
A final shot: index entries that are obscure or questionable probably
won't do much harm (if they really point to something), because people
unfamiliar with a term are not likely to look it up ... IMHO of course!
I'm interested to see what other responses LaVonna's message provokes.
Mike Beyries (beyries -at- csisdn -dot- com) __________________________
Technical Writer & Doer of Other Foul Deeds | Every stinking smell |
Located at Connective Strategies, Inc. | that fights it out with |
Phone 415-903-8382 or -2589 | a ventilator imagines |
| itself Don Quixote. |
| -- Stanislaw Lem |
*NOT* CSI's corporate opinion at all! |__________________________|
*not* CSI's opinion