Documenting wizards? (take II)

Subject: Documenting wizards? (take II)
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 14 May 2003 09:48:21 -0400

Rebecca Downey raised an important addition to my previous comments: <<I
often had to document the wizards. Technical support teams wanted
wizard-walk-throughs that showed all the screens, what to do on each page
and all the possibilities mapped out... So yes, Wizards should not need
traditional online help for the user to use them; but considering that there
are other classes of people than users for which you write documentation -
you may still have to document your wizard.>>

I assumed, perhaps without merit, that the documentation was user-centered,
and as you note, there's a difference between user docs and
designer/developer docs. Good point. Some of our recent and past threads on
API documentation could provide solid guidance in this area.

Goober Writer responded to my comments on self-documenting wizards: <<I
agree with the gist but not with the notion that a
wizard that could benefit from help is a failure. Wizards are indeed used to
facilitate a task, but sometimes a task can be inherently complex, with or
without a wizard... sometimes the information being requested by the wizard
can be complex enough to benefit from online help.>>

Think of it this way: Users want access to the information. You can present
the information as online help, which takes them away from the task, or as
embedded help, which keeps them focused on the task. Contextual information
(e.g., why I'm doing this task) can easily go in the printed docs or online
help, but once you're in the wizard, you shouldn't have to leave the wizard
because that's taking you away from the task at hand. Integrating the help
with the task is why embedded help is such a hot topic nowadays.

Complex information can usually be broken down into a longer series of
simple steps, and that's the kind of design decision you can make in the
wizard too. For example:
"In this step, you're going to choose between two Linux boxes:
[radio button] Intel-based
- make this choice if...
[radio button] Sun (Sparc) based
- make this choice if..."

No need to create separate online help that explains the difference between
PC and Sparc computers... explain it right in this step. The obvious
tradeoff, of course, is that you need to know your audience. A really techy
audience such as network admins may not want this level of detail and may
want fewer screens in the wizard (efficiency) rather than simpler screens
(simplicity), but may still appreciate the structure and guidance provided
by a wizard. For such audiences, you may indeed want the online help
approach. But I suspect that most users want the information in the

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

"I have always wished that my computer would be as easy to use as my
telephone. My wish has come true. I no longer know how to use my
telephone."--Bjarne Stronstrup (originator of C++ programming language)


Robohelp X3, from eHelp, lets you quickly and easily create
professional Help systems for all your Windows and Web-based
applications, including Net.

Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module.

Order RoboHelp today:

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: Documenting wizards?
Next by Author: RE: Please recommend an ergonomic desk in Ottawa, Canada
Previous by Thread: Word heading-number question
Next by Thread: Re: Documentation Manager: does it always include managing a team?

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

Sponsored Ads