TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
interface.
--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)
---
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.
