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

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

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
www.raycomm.com/techwhirl/usersadvocate.html

"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.  http://ieeepcs.org/2001/

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

---
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 
http://www.raycomm.com/techwhirl/ for more resources and info.