Re: Indexes

Subject: Re: Indexes
From: Mike Pope <mikep -at- ASYMETRIX -dot- COM>
Date: Wed, 30 Mar 1994 18:22:00 PST

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?)
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
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',
'cancelled'") -- lots of fiddly bits that you might need to know about, but
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
such that it might still need one. Hmmmm.


-- Mike Pope
mikep -at- asymetrix

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

Previous by Author: Re: Nancy Burn's Glossary Suggestion
Next by Author: Usability Seminar
Previous by Thread: Indexes
Next by Thread: Please tell me this is an April Fool's gag

What this post helpful? Share it with friends and colleagues:

Sponsored Ads