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

[Bonnie Granat <bgranat -at- att -dot- net>]

John Posada wrote:
> 
> 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."
> 

The following is misleading:

"a 'period' after the @ sign that has characters on both sides of it," 

Unfortunately, this phrase can be read incorrectly. The entire paragraph
could be rewritten so that it is half its size and does not introduce
ambiguity.

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

I believe it is standard to give *one* method of choosing commands (menu or
keyboard shortcuts) throughout documentation. It might be helpful to
remember that "keyboard shortcuts" are just that -- shortcuts -- and not
the standard method of choosing commands.


-- 
Bonnie Granat
http://home.att.net/~bgranat

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

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.