Inclusion of field descriptions in help systems?

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

David Goldberg wonders: <<I would like to know how others handle the
definition of fields in non-context sensitive Help systems for large
software applications, particularly using the RoboHTML and WebHelp products.
>>

Well, first off, I try to get the developers to make the help
context-sensitive. Once they see how easy it is, they usually cave in and do
the work. That's not always possible, of course.

<<Do you put all application field definitions in a common glossary and link
to the glossary from the procedural topics?  Do you have separate field
description topics per application screen and list the definitions there? Do
you use techniques like text-only popups to display the field definitions
without having the user leave the procedural topic?>>

I've used all three approaches at one time or another, separately or in
combination; I like the popups least well because they make a visual mess of
the screen if there are lots of glossary words, and they're annoying to
create (particularly since I have to maintain a French version of the file
simultaneously). Currently, I try to define the fields exclusively in the
context of the topic that describes their dialog box, on a twofold logic:
first, this doesn't require readers to jump out of their current context and
back again and second, the only time they're really likely to look up a
field is if they're already in the dialog box that contains it. One thing
I've found that works very well is to start each topic with a mini-table of
contents. So for example, a typical topic might look like the following:

Dialog box topic
	This topic contains:
	Introduction
	Tab A
	Tab B
	...
	Tab X
Introduction
	This is the intro... [and so on]

Each of the items in the TOC is hyperlinked to a mid-topic heading (such as
"Introduction") so the user can jump directly to what interests them, while
the TOC itself serves as an overview of everything in the topic so they'll
know whether they're in the right place. On the other hand, if they read
linearly through the topic, they get the information presented in what I
consider to be a logical sequence. In your case, "Tab X" might be replaced
by "Field descriptions". Keeping everything in a single topic lets users
print the topic and get only a single printout (rather than multiple
printouts that must be collated, as occurs if they have to jump to a
separate glossary). It's also an efficient design: the index lets them jump
right to the top of the topic that contains a given field (one click), where
they see that they have to click "Field descriptions" to get to the
descriptions (another click), after which they scroll alphabetically to find
the correct field. I also use non-alphabetic ordering of fields based on the
visual sequence when there are relatively few fields, and the help topic
seems to support this approach (i.e., they'll scan through the help in the
same order that they scan through the fields). I confess to being a bit
subjectively inconsistent in this approach.

<<I have yet to identify an optimal solution.>>

Nobody has. Online help is too young a field (ca. 10 years in its current
form) for anyone to have found the optimal solution yet. Plus, I suspect
that this is one of those areas of endeavor in which there will always be
multiple roughly comparable solutions.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."-Kim Roper 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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