Re: Indexing information

[Mike Beyries <beyries -at- CSISDN -dot- COM>]

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
   and figure.
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
   as well.
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
   your index.
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.

Regards,
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