Fields arranged as a sentence?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Lindsey Durway wonders: <<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 like this approach; as you noted in your original message, it's an elegant
way of communicating the decision logic to the user.

<<I find this type of style awkward to document.>>

If it's written properly (as it seems to be in the example you provided), it
should be largely self-documenting; where the meaning isn't clear, you have
a chance to build the help into the interface by rewriting it (thereby
providing "embedded help"). Because the logic is clear, all you need to do
is explain the different options enclosed in < > to the reader. An easy way
to do this is to provide a screenshot of the interface, with little call-out
arrows pointing at the fields. In the callouts, explain the options if
they're not already self-explanatory.

<<I'm thinking of proposing a label-oriented style like the following:
Variable name: <variable-name>
Comparison operator:  <greater-than/etc.>

Nothing wrong with that approach either, though it's arguably slightly less
"efficient" for the reader than a screenshot-based approach because readers
have to glance away from the context (the screenshot) to see the details
available in that context. If you find screenshots difficult to annotate or
if the annotations might be too long for that approach to work well, you
could certainly follow the screenshot with a table of values for the fields
rather than using callouts.

<<The audience will mostly be from our own stable of experts--our typical
customer doesn't configure our software... Anyone have strong feelings about
this?  Suggestions?>>

I'd wager that your "stable of experts" will have opinions. <g> Why not ask
them? Working to make their lives easier is a great way to build
relationships you'll be able to count on later when you need a favor.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"By three methods we may learn wisdom: First, by reflection, which is
noblest; second, by imitation, which is easiest; and third, by experience,
which is the bitterest."--Confucius, philosopher and teacher (c. 551-478
BCE)


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