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:Indexes and Alphabetic References From:"Less is more." <yvonne -at- SATURN -dot- SMARTSTAR -dot- COM> Date:Thu, 31 Mar 1994 08:33:37 -0800
Mike Pope <mikep -at- ASYMETRIX -dot- COM> writes:
> 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.
In response to some informal usability testing, we changed our alphabetic
reference from separate alphabetic chapters for objects, attributes, methods,
and language statements to one big alphabetic chapter. People can't remember
whether something is a built-in function or an object method. It works much
better all folded in togther.
> 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',
> and 'cancelled'") -- lots of fiddly bits that you might need to know about,
> but which wouldn't be entries in and of themselves.
You still need lots of indexing in an alphabetic reference. For example, if
you have a "switch" statement, you need to index it under "case" statement
for users with different programming language backgrounds. Also, a topic
can contain subtopics or details that need to be indexed. The examples for
one topic might be useful in understanding other language constructs.
All these things should be indexed. You might be able to eliminate the one
index entry for the name of each topic. But, that makes things confusing
for the users who look in the index first.
I don't think the index is the place to skimp when you are trying to write
minimalist (or at least shorter) manuals.
-- Yvonne DeGraw
Santa Barbara, CA
yvonne -at- smartstar -dot- com