Indexes and Alphabetic References

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
SmartStar Corporation
Santa Barbara, CA
yvonne -at- smartstar -dot- com

Previous by Author: Re: (Was Glossaries etc.)
Next by Author: Re: job titles
Previous by Thread: Words Into Type 4th ed.
Next by Thread: "Using this Book"

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

Sponsored Ads