RE: Indexing of reference manual? (Take II)

Subject: RE: Indexing of reference manual? (Take II)
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 18 Oct 2001 08:31:07 -0400

Martina Sasnauskaite provided more information: <<what if the TOC of the
reference manual is structured alphabetically?>>

Then it's an index. <g> Seriously, though, if it simply follows the topics
in alphabetical order, then that's the appropriate structure, but it still
doesn't solve the reader's problem: "How do I find a specific topic when I
don't know what name the developers gave it?" The answer is, of course, to
come up with my own name for it and see whether that name is in the index.
If not, I try another name, and another, until I give up and ask the woman
down the hall who's our local expert in this software.

<<Then what do I have to do? To rewrite the TOC and to add in the index all
the names of the buttons, such like - OK, Cancel? What should be included? I
think the main target of the reference manual is to describe the GUI?>>

As noted above, you need to be able to think like a user of the manual: What
are they looking for? (Not the OK button, but the task that you get the
software to do when you press OK.) What names will they use to look for it?
(Think synonyms.) If you can't answer either question yourself, then you
need to ask it to people who can provide answers: your audience, of course,
but also tech support staff, trainers, sales staff, etc.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at

"The problem with defending the purity of the English language is that
English is about as pure as a cribhouse [We're Happily Overcoming Repulsive
E-mailfiltering]. We don't just borrow words; on occasion, English has
pursued other languages down alleyways to beat them unconscious and rifle
their pockets for new vocabulary."-- James D. Nicoll

Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.


Previous by Author: Indexing of reference manual?
Next by Author: Line breaks in pdf?
Previous by Thread: RE: XML as Help Format
Next by Thread: Re: Indexing of reference manual? (Take II)

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

Sponsored Ads