TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
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.