How much do people need to be told in documentation? (take II)

Subject: How much do people need to be told in documentation? (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: Mon, 17 Sep 2001 13:22:21 -0400

Bruce Byfield generally agreed with my statement that "The standard rule of
thumb for such things is emphasize only one way to do things in the text,
but provide a list of shortcuts and alternatives somewhere" but: <<I've made
an exception in the last few years for documentation aimed at Linux
beginners. I had two reasons: - I wanted new comers to realize the full
range of options. - More experienced Linux users, who might also use some of
the material, are both completists and individualistic in their work
methods. In other words, they want to know all the options, and dislike
being herded (as they would see it) towards using one method only.>>

That's an excellent example of knowing your audience and writing to meet
their needs, and that uber-rule supercedes all the other rules of thumb we
often quote on this list.

<<This second reason is, in fact, my largest qualm about using only one
method in the text. If only menu commands are mentioned, then the majority
of users may only know the menu commands. They may never learn the keyboard
commands, which are often more efficient.>>

Alerting them to the other possibilities is certainly important; one obvious
way to to do it is to include shortcuts in the margins or provide a
quick-reference card (as I noted), but another is to make this instruction
part of the tutorial or even part of a "tip of the day" feature in the
software. Those are by no means the only ways to accomplish the task. In
fact, that might make an interesting thread all on its own: how do you alert
readers to alternative, more-efficient ways to do things? (If anyone takes
me up on this and starts a new thread, PLEASE change the subject/title of
the messages!)

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

"How are SF writers like technical writers? Well, we both write about the
things we imagine will happen in the future!"--Sue Gallagher


A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: +++

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: Context-sensitive help: mapped to another key than F1?
Next by Author: Minimalist manuals: a misconception
Previous by Thread: Context-sensitive help: mapped to another key than F1?
Next by Thread: Informing Users of Alternatives (was: How much do people need to be told ...?)

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

Sponsored Ads