TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
document.
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?"
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.comhttp://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.
