RE: Field-specific Help

Subject: RE: Field-specific Help
From: "Andrew Warren" <awarren -at- synaptics -dot- com>
To: "l m" <lm5582002 -at- yahoo -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 16 Aug 2007 16:51:47 -0700

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


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

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

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

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

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 for more resources and info.


Previous by Author: Firefox Cache (was: "RE: Flare and SharePoint (overview)")
Next by Author: RE: icons vs. buttons?
Previous by Thread: Re: Field-specific Help
Next by Thread: Re: Field-specific Help

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

Sponsored Ads