How much do people need to be told in documentation?

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

John Posada wonders: <<How much do people need to be told in
documentation.>>

Much less than they used to. When was the last time any of us wrote "Here's
how to use Windows"?

<<Do you really think... that we need to use a full paragraph explaining to
them what an email address looks like?>>

No more than we need to explain to them how to spell English names. Anyone
who's entering an e-mail address must spell it correctly: if they do, then
they don't need instructions about what the address looks like, but if they
don't, then it really doesn't matter how many pages of instructions we give
them. What would be important in this case is to document any exceptions
(e.g., "our software can't handle e-mail addresses longer than 12
characters") and perhaps include appropriate cautions (e.g., "double-check
your address; if it's wrong, we'll have no way to respond to your query").

<<The other issue ivolves something as simple as copy and paste.  In the
document, I explain one way CTRL-C and CTRL-V. He insists that everywhere I
use the instruction to copy or paste, that I also include the alternate of
Edit-Copy and Edit-Paste. I eally don't care which one...>>

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 (typically in an appendix or a separate topic in the online help).
In my documentation, I present only the menu commands as the primary means
for performing various tasks, on the logic that this way _anyone_ can get
the task done; experts will quickly figure out the shortcuts (ideally, all
are listed beside the menu choices) or will look them up in an appendix. If
we provide only the keyboard commands, then people (and there are many) who
can't remember keyboard shortcuts and who prefer to use the mouse will be
working at a severe disadvantage. I'd make an exception here for an audience
comprising primarily power users, who may prefer the keyboard shortcuts.
Even then, I'd still suggest presenting the menu route as the primary means
of accomplishing a goal, with the keyboard shortcuts presented in the margin
or perhaps on a quick-reference card.

--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.