RE: How much do people need to be told in documentation.

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

> -----Original Message-----
> From: John Posada [mailto:jposada01 -at- yahoo -dot- com]
> Sent: Monday, September 17, 2001 8:37 AM
> To: TECHWR-L
> Subject: How much do people need to be told in documentation.

> Two issues. I'm documenting a script where the person using the
> script must fill in a form and some of the form fields require an
> email adddress. He insists on including a full paragraph on what a
> valid email address looks like.

Better too much information than not enough. Readers have been trained
from countless hours watching television and reading newspapers to
ignore the ads and the irrelevant things.

I don't think it will hurt to have this explanation of a fully qualified
e-mail address.

However, I would support you in your efforts to bury this in a pop-up or
glossary.

> 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. 
 
The first time the topic of copy and paste comes up, you can certainly
provide the six-gazillion ways that this can be accomplished. (Hot keys,
pull-down menus, toolbar icons, etc.)

However, I'm in favor of only showing one version from them on.

Although I support Ctrl+C and Ctrl+V, a very strong consistency argument
can be made for always describing your software from pull-down menus.
The reasoning is that not all pull-down menu items have hot keys, so
you'll have to describe how to get those pull-down menus anyway. The
menu items that do have hot keys usually have those key combinations
written next to them, which re-enforces an alternative way. Hence, every
time they go into the Edit pull-down menu, they'll see "Copy [Ctrl+C]",
etc.

Stick to your guns about consistently showing one way to do it, but be
open about which way you show.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.