How to document multi-choice GUI?

Subject: How to document multi-choice GUI?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 4 Mar 2003 13:11:19 -0500


Patrice Dodd wonders: <<In a new software product, designed to allow the
user to create a custom multimedia CD, the user makes several selections
within one GUI window. This window has six sections. Each section contains
several options, and the choices available in the other five sections will
change depending on which options the user selects in each section. Because
of this structure, to complete the task of making the CD, the use must make
a series of choices in each step. By the time the user gets to the end,
there are myriad possibile task flows.>>

The first thing to recognize is that even if there are myriad task flows,
you can always come up with a single logical flow. For example, the GUI
window itself dictates the flow that users are most likely to follow: start
at the top left, and work down towards the bottom right. If this approach is
completely inefficient, then the user interface must be redesigned, and
don't take any "we can't do that" from the developers; rearranging the order
of screen elements without touching the underlying code is trivial in any
modern programming language.

Sometimes there are several completely different flows, each for a different
purpose. If that's the case, the flow isn't really that much more
complicated. Create a help topic as follows: Click on the following links to
learn how to (i) Create a disk image, (ii) Make an audio CD, or (iii) Create
a multimedia extravaganza". Each of those links goes to a help topic that
explains a logical flow to achieve each of the three goals.

If the approach dictated by the order of elements in the GUI is at all
reasonable, you can easily document the overall task by following that
order. Simply create six steps (since you mentioned there are six sections
to the window) that follow the order of the screen elements. This forms the
basis for your first help topic: "Here's one sequence we've found to work,
even if other approaches might work equally well." Add a useful suggestion
such as the following: "To help you work through these steps, we've linked
each step to a new help topic that provides full details on that step.
Keeping the help window open, work through all the individual details for
that step, then click the Back button in your help software to return to
this overall list of steps so you can continue with the next step."

Each of the steps in this first help topic can link to a new help topic that
describes the various options for that step. Where an option becomes
unavailable because of a previous selection, it's easy to explain this. For
example, in one product I'm documenting, I have the following: "If the
Activity codes tab is unavailable, this is because you selected the MultiDAT
Jr configuration on the General tab. Deselect that option if you want to use
Activity codes."

Why does this work? It provides a high-level overview (6 steps) for those
who already know the details and just want to be reminded what procedure to
follow; this same overview also teaches the innocent and the inexperienced
how to proceed. For those who want more details, they're available at the
click of a button--via a link to the help text that explains the details for
that particular step. And this approach works hand in hand with the software
(if you keep the Help window "always on top") to move the user through the
procedure.

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

"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Order RoboHelp Office X3 by March 14 and receive a $100 mail-in rebate,
plus FREE WebHelp Merge Module and FREE iMarkup Software, for a
total giveaway value of $439! Order today at http://www.ehelp.com/techwr-l

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday 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.



Previous by Author: Gender neutral? Myths (Take III)
Next by Author: Category vs. alphabetical listing in contents tab in online help?
Previous by Thread: Re: Car-seat Instructions Too Difficult, Says Study
Next by Thread: RE: car seats, tech writing, and literacy


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


Sponsored Ads