RE: Field-specific Help

["Andrew Warren" <awarren -at- synaptics -dot- com>]

l m wrote:

> My contention is that for the fields like "Name," "Address,"
> "Phone Number," etc. we do not need online help defining these
> fields!
> ....
> Do I really have to write, "In the Name field, enter your
> name."???

LM:

No, that'd be a pretty braindead way to document the software... But
think about what IS important -- i.e., what assumptions the software
will make about the text entered in those fields -- and document THAT.

In my opinion, you can do without the documentation only if either no
assumptions are made, or if the assumptions are guaranteed to be shared
by all the users you care about.

For instance, if your software and your business processes will
gracefully accept and operate properly on each of these names:

    "Prince" (only one name),
    "Charles" (first name only),
    "Windsor" (last name only),
    "Charles Windsor" (first and last),
    "Windsor, Charles" (last followed by first),
    "Mr. Windsor" (title and last),
    "Prince Charles" (title and first), and
    "His Royal Highness Prince Charles Philip Arthur George,
     Prince of Wales, KG, KT, GCB, OM, AK, QSO, PC, ADC, Earl
     of Chester, Duke of Cornwall, Duke of Rothesay, Earl of
     Carrick, Baron of Renfrew, Lord of the Isles and Prince
     and Great Steward of Scotland",

then you may not need to document the "Name" field.

If the software does the right thing when the Address field is filled
with:

    just a street address,
    just the city and/or state,
    a street address with city and state,
    a complete US address including 5- or 9-digit ZIP code,
    a three-line US address,
    a four-line US address,
    PO boxes,
    APO/FPO addresses,
    all the various permutations of non-US addresses... AND
    email addresses,

then you can safely leave off Address-field help, too.

I've not yet seen an application smart enough to parse
unrestricted-input worldwide telephone numbers.  Unless yours is the
first, I'd recommend including "Phone Number" help.

-Andrew

=== Andrew Warren  - awarren -at- synaptics -dot- com
=== Synaptics, Inc - Santa Clara, CA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.