Re: Indexes

[Mike Pope <mikep -at- ASYMETRIX -dot- COM>]

Mike Christie says:

>In my spare time at home, I frequently refer to the language
>reference for a well-known PC communications program. The
>commands are in one section, the set statements in another, etc.
>Although everything I need to know is there, the alphabetized stuff
>is not indexed, and not always where I expect to find in. Annoys the
>heck out of me. Just 'cause it's alphabetical (in the glossary or
>anywhere else) doesn't mean it shouldn't be in the index too!

This is evidence (in my experience) of program language documentation
organized by how the compiler works, rather than how a user will likely
need to look things up. A classic version of this is a reference (as here?)
that
has one alpha list of commands, another of functions, and a third of (e.g.)
operators. This never works for users, who don't necessarily know and often
care even less whether something is a command or a function or whatever.
Analogy: imagine looking in a dictionary and having to determine first
whether the word you're looking for is a noun or a verb, because they're in
separate sections.

Ok, soapbox stepped off from, would you need the index if everything were
strictly alphabetical? Or maybe need it less, should I ask? The only time I
can
imagine an index to be very handy in an alpha reference is if there are lots
of keyword values ("the return values for this function are 'ok', 'error',
and
'cancelled'") -- lots of fiddly bits that you might need to know about, but
which
wouldn't be entries in and of themselves. (Or would they be? Different
discussion, see "Encyclopedia Model". <g>) Encyclopedias don't have indexes,
that's clear -- an interesting question to ponder is how reference doc is
different
such that it might still need one. Hmmmm.

Cheers,

 -- Mike Pope
mikep -at- asymetrix

PS though it may sound like it from my email, I'm not anti-index at all.