Help for large dialog boxes?

Subject: Help for large dialog boxes?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 19 Sep 2002 14:14:47 -0400

Donna Marino reports: <<I'm writing help text for some dialog boxes in an
application. There are numerous controls and features on the dialog box and
the help topic is turning out to be very long (too long to read on screen,
in my opinion).>>

If the dialog box follows any kind of logical organization (see below), you
can divide the help topic up into groups of related functions. Let's say,
for instance, that the first third of a dialog box containing personal
information on customers deals with addresses, the middle third deals with
demographics, and the last third deals with easily hacked information that
could ruin someone's life. The help topic begins with the following text:

Personal information
This topic contains help on the following sections of the InsanelyBig dialog
- address information
- information on your net worth
- carefully protected confidential information

Each of the bullets should be formatted as a hyperlink, and each section
reached by means of these hyperlinks should have a "back to top" link.
(Yeah, you can always use the "back" button, but why assume users know how
to use this in a help file?)

<<Users really need this information, too, because the dialog boxes are not
very intuitive.>>

Why not spend some time discussing improvements with the developers? If
they're using any development software released since (say) 1997, it's a
trivial matter to rearrange the various interface elements until they make
sense, and anyone who tells you differently is lying. Work with them to
redesign the interface so that it's effective. Primitive way: print a
screenshot, cut out all the interface objects, and tape them (after suitable
pen and ink editing) onto blank paper in a more logical sequence.
Sophisticated way: check out the following article (but note that you can
also use Word to do this work, and probably should):
Hart, G. 2001. Using VBA to prototype a software interface.

<<I've thought about links that take users to subsequent topics, instead of
putting all the info in a single topic, but I don't want them to have to
jump a million places in order to get help.>>

Another few ways to make this work better: If you can persuade the
developers to let you play with the interface, group and organize the labels
so as to make the meanings clear. Add affordances (e.g., "date YYYYMMDD"),
group related fields, make the fields follow the order in which they're
accessed by the readers, use white space to separate groups of unrelated
fields, etc. etc. Second, propose that they break the one large dialog box
into a smaller tabbed dialog box, and create a separate help topic for each

--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
"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."--Kim Roper

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever!

Enhance, optimize and automate your FrameMaker-to-PDF workflow with TimeSavers:
Define all PDF features in your source FrameMaker files ONCE, distill MANY.
Bookmark Controller, Link Controller, UnBloat & more :

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

Previous by Author: Quick reference material in user guide?
Next by Author: Funny technical writing--risky?
Previous by Thread: Re: help for large dialog boxes
Next by Thread: References a later chapter

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

Sponsored Ads