Documenting wizards that have numbered "steps"?

[Geoff Hart <ghart -at- videotron -dot- ca>]

L. Migliorini wondered: <<I have to document a wizard that has numbered 
steps - that is, the words "Step 1 Step 2, Step 3," etc. appear right 
on the dialog and as part of the name of that tab.>>

I'm curious: why are you documenting a wizard? A well-designed wizard 
should be self-documenting. After all, the whole purpose of creating a 
wizard is to walk the user through a task so that they don't have to 
consult the documentation and thereby embed the documentation within 
the actual task.

From what you say below, it sounds like this isn't a true wizard, since 
the user must somehow understand that they must switch manually from 
tab to tb (thus, the need for documenting the use of the tabs). That's 
a significant design problem, since the wizard should handle this 
detail for the user, and should not confuse the user by presenting 
multiple tabs. Each tab should be presented only when the user is ready 
for it. Otherwise, why use a wizard in the first place? Simpler just to 
present a tabbed dialog and document that.

Note that when you use wizards, the task changes from "accomplish X" to 
"follow the steps in the wizard" (which will lead me to accomplish X). 
This changes what you're documenting and how you're documenting it.

<<But of course, in the procedure I am writing, there are a few steps 
that you must take before you even get to the wizard Step 1, so the 
"steps" will always be out of synch.>>

Presumably these steps should also be numbered, but since they aren't 
part of the instructions for using the wizard, they clearly belong to a 
different section and should have a different numbering scheme. That's 
simpler and clearer than worrying about how the labels in the interface 
("Step 1" on the first tab, etc.) correspond to your instructions:

<<1. go to such and such and log on
2. navigate to such and such and change your options
3. change the path names and do blah blah
4. Use the Wizard.
   a. Step 1
   b. Step 2
   c. Step 3
   d. and so on.>>

In this case, you'd have two sections in your documentation: One called 
"Before you begin", which would have steps numbered 1-3 to match the 
numbers in your example, and a second section called "Using the 
wizard", where a-d (in your example) are replaced by 1, 2, and 3 to 
match the tabs.

Better still, why not use "Before you begin", "Step 1", "Step 2", etc. 
as the subheading in your documentation? These subheadings would then 
parallel the use of tabs in the wizard, and that's probably the most 
effective strategy.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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

New from Quadralay Corporation: WebWorks ePublisher Pro! Easily create 
14 online formats, including 6 Help systems, in a project-based 
workflow. Live, online demo! http://www.webworks.com/techwr-l

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author 
content and configure Help in MS Word or any HTML editor. No 
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.