indexes & such

[Bonni Graham <bonnig -at- IX -dot- NETCOM -dot- COM>]

I've found that the best way to approach an index is to remember that
users open it because they have a question.  They suspect that the book
contains the answer to the question, so they open the index looking for
a reference to the page containing the answer.  If you ALWAYS bear in
mind that you're providing the pointers to an answer, what to index
becomes easier.  Index the things that someone looking at whatever
you're documenting might question:

o how do I operate the framis?
    framis
       operating.........x

    operating
       framis............x

o what is a framis?
    framis
      definition.........x (perhaps)
      operating..........x

    framis...............x (another option)

o what is the framis goobulator?
    framis...............x
      goobulator.........x
      operating..........x

o what's the difference between the framis and the widget?
    framis...............x
      goobulator.........x
      operating..........x
      widget, and........x (perhaps)

    framis...............x
      goobulator.........x
      operating..........x
      widget, differences
       between...........x (perhaps)

o what is a thingamajig (old term for a framis, but this user doesn't
know that)?
     thingamajig
        SEE framis

You get the idea. Creating an index is NOT easy.  You have to think not
only like a user, but like a confused, possibly even aggravated, user.
It's not impossible to, but you do have to work a little at it.

Bonni Graham
Manual Labour
"If they have to look it up, they're already aggravated"
B. Block, San Diego Technical Writer