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.
Subject:Documenting every field From:Emily Skarzenski <eskarzenski -at- DTTUS -dot- COM> Date:Fri, 2 Feb 1996 14:33:36 CST
Tracy Boyington writes:
> > one problem we're seeing with new stuff, is "pointless help". got a
> > dialog box with a field that says "file name" and an OK function
> > button and you click the help key and get a nice dialog that says
> > things like "this is the file name field". no duh.
> This is my pet peeve and yet my engineers absolutely INSIST that I do
> this! I hate it! They want every field in every window and dialog box
> to have a separate topic. I've thrown fits but to no avail. How much
> can you say about a field titled "Last Name" or "City"? It's just
> plain ridiculous
How do you decide which fields to document and which fields are so
obvious that you needn't? At my last job, I documented a data-entry
package that allowed users to enter three addresses (a headquarters
address, a store address, and a warehouse address). In that case, it was
important that we document all those "obvious" fields like address,
city, state, and zip so that users knew which address they were
Regardless, deciding which fields users need help with and which they
don't is tough. Trying to get consensus out of other people that work on
the project (marketing people, tech support staff, etc.) is even harder.
In my experience, it's nearly impossible to find any field that some
poor novice user might not know how to fill in.
So... in the past, I have documented every field by choice. Usually, I'm
too busy putting out *real* fires to second-guess what users will know
and what they won't. Besides, as others have mentioned, it's easy enough
to put *some* kind of valuable information into a field's help topic.
Deloitte & Touche/ICS - Chadds Ford, PA
eskarzenski -at- dttus -dot- com
71220 -dot- 341 -at- compuserve -dot- com