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

[Tom Murrell <trmurrell -at- yahoo -dot- com>]

--- John Posada <jposada01 -at- yahoo -dot- com> wrote:
> 
> What I have done is make an alternate suggestion to the developer. My
> suggestion is to include the following line the first time they are
> instructed to enter an email adress:
> 
> "The email address should be formatted as XXX -at- Avaya -dot- com -dot-  Example:
> joesales -at- avaya -dot- com -dot- "

John,

Obviously, this issue is important to the developer, but it seems an even more
obvious solution may have been overlooked. If it is absolutely vital that the
email address be entered correctly, have that field checked to make sure it is
in the format specified. If the email address is not correctly entered, the
developer can print an error message and return the user to the field in the
form that needs to be fixed. (Of course, there is no protecting the user from
entering an invalid email address that is in the proper form.)

But, to throw my two cents in on the original question, the suggested text is
overkill, especially in light of the fact that your audience knows what email
is and what their email addresses are. You're an experienced writer; tell
somebody to get this bozo off your back so you can do your job.

=====
Tom Murrell
Lead Technical Writer
Alliance Data Systems
Columbus, Ohio
mailto:tmurrell -at- columbus -dot- rr -dot- com
Personal Web Page - http://home.columbus.rr.com/murrell/
Page Last Updated 07/15/01

__________________________________________________
Terrorist Attacks on U.S. - How can you help?
Donate cash, emergency relief information
http://dailynews.yahoo.com/fc/US/Emergency_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.  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.