How much do people need to be told in documentation.

Subject: How much do people need to be told in documentation.
From: John Posada <jposada01 -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 17 Sep 2001 07:37:11 -0700 (PDT)

Hi, guys...I'm having a back-and-forth with one of my senior
developers (in fact, THE most senior) and it involves editss to my

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.

This is his explaination:

"Any email address that is entered in the SmartScript should be of
the format of ? A -at- A -dot- A where A is any series of numbers and letters.
It is important that the @ sign be included and that there is a
?period? after the @ sign that has characters on both sides of it,
thus a fully qualified email address, example: joesales -at- avaya -dot- com -dot-
If the @ sign and the ?period? with its conditions are omitted it is
possible that the email will not be delivered. These are the same
rules that apply when you send an email using Avaya?s Microsoft
Outlook software."

My rsponse is:

"Do you really think that with people knowing what they know, that we
need to use a full paragraph explaining to them what an email address
looks like? As most people know by now, I usualy assume very little
in a document, but I think explaining that an email address contains
an @ sign, a period after the @ sign, etc. may be overkill."

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, but my response has been:

"You want me to give multiple ways of copying and pasting. My opinion
is that we give them one (CTRL-C and CTRL-V). This way we know they
CAN do it. If they know of other ways, then they'll use them anyway.
Are there any situations where using keyboard commands won't work,
and therefore, must use the alterrnate method?"

Opinions on either?

John Posada, Senior Technical Writer
mailto:john -at- tdandw -dot- com, 732-259-2874

Terrorist Attacks on U.S. - How can you help?
Donate cash, emergency relief information


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: Re: Word HTML TOC problems
Next by Author: Re: How much do people need to be told in documentation.
Previous by Thread: Re: UNIX manual page development tool
Next by Thread: Re: How much do people need to be told in documentation.

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

Sponsored Ads