Re: Indexing information

[Bonni_Graham_at_Enfin-SD -at- PROTEON -dot- COM]

Yay!  A substance question!  (I know, I know, I've been just
as bad as anyone, but I AM glad to have an _issue_)

Lavonna asks:
"4.  If you have any golden rules for indexing manuals, what
are they?"

I'm not a professional indexer, but I play one at my job.
               ;)

Actually, I do pretty well indexing, I feel.  I learned in
the school of hard knocks -- indexing for library automation
software.  Believe me, NO ONE is pickier about an index than
a librarian.  AND they can tell you how to fix it, which is
really great.

One of my major rules of thumb is that there should be no
entry that you can get at only one way.  In other words, for
every term you index, find another way to say it and index
THAT, too.  Then keep doing it every time you revise the
manual.

Go to your SMEs and find out if there are synonyms for
crucial terms.  For example, in SQL, you can define a
simpler name for a table that the one required by the
hardware.  This is called an alias.  It's also called a
correlation name.  Even if your software only calls it an
alias, index it under correlation name, too.

Use plenty of SEE and SEE ALSO references, especially if
you're trying to teach your users to use new terminology.
I'm currently indexing a Smalltalk manual aimed at
programmers who are familiar with structured programming
only.  I have a SEE reference for every structured term that
has an equivalent concept in object orientation (and an
entry for the OO concept).  Why SEEs and not SEE ALSOs?
Because we're trying to teach them to not be structured
programmers anymore, to give up their old terminology, if
you will.  The index can be used for instruction, as well as
reference.

Don't be afraid to duplicate entire sections of information.
"class source" and any associated secondary or tertiary
references should also be under "source, class".

My rule of thumb for amount is that there should be at least
1 page of index for every twenty-five pages of manual.
Given that the index page to which I am referring is set in
two-column 8-point, while the manual is in one-column
10-point, you see that many entries are necessary.

I'm thinking about preparing a workshop on indexing for my
next year's doc-and-pony show.  What do y'all think?  Worth
it?

Bonni Graham                               |
Technical Writer                           | Most software is run by
Easel Corporation, ENFIN Technology Lab    | confused users acting on
Bonni_Graham_at_Enfin-SD -at- relay -dot- proteon -dot- com | incorrect and incomplete
President, San Diego STC                   | information, doing things
                                           | the designer never expected.
NOTE: apparently my email address needs    |
to be typed exactly as it appears here,    |          --Paul Heckel, quoted
punctuation and all, or the system gets    |            by William Horton
upset.                                     |