Re: Fields arranged as a sentence

["Richard G. Combs" <richard -dot- combs -at- voyanttech -dot- com>]

Lindsey Durway wrote:

> I'm documenting a GUI operation that requires the user to enter several
> arguments. The programmer has arranged these fields as a sentence, sort of
a
> fill-in-the-blanks thingie.  It looks like the following, where the angle
> brackets indicate the fields & the type of value that the field accepts:
>
> If <variable-name> is <less-than/greater-than/equal-to> <number> then
> generate <event-type>.
>
> I find this type of style awkward to document.

I wholeheartedly agree with Dick and Lisa. This is far more user-friendly
and self-explanatory than the "label-oriented style" you're considering. The
"traditional" field labels have only one advantage: the writer can easily
name things without having to think about or understand what the reader is
really being asked to do. ;-)

Dick suggested that you "just slow down a little and bite of smaller
chunks." I have to disagree just a bit. Slow down, yes -- but then, try
thinking about the big picture first instead of the individual bits of
information. I assume you're writing task-oriented documentation. Think in
terms of what the reader accomplishes by performing this step. Hint: It's
not "completing the variable name, comparison operator, and event type
fields."

As Geoff just suggested, your programmer is providing embedded help, and
proposed sentence is essentially self-documenting (especially if the
interface provides lists of valid values). You should concentrate on telling
the reader about the purpose of this step and the consequences of different
choices, not describing the fields themselves.

Richard


------
Richard G. Combs
Senior Technical Writer
Voyant Technologies, Inc.
richardDOTcombs AT voyanttechDOTcom
303-223-5111
------
rgcombs AT freeDASHmarketDOTnet
303-777-0436
------










^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

Order RoboHelp X3 in November and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l

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