Documenting wizards that have numbered "steps"?

Subject: Documenting wizards that have numbered "steps"?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 01 Jun 2005 13:42:56 -0400

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


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

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.

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

Previous by Author: Re: User rant
Next by Author: Question in MSWord using English (UK) Spell Check?
Previous by Thread: Re: ADMIN Re: Clearances (was Outsourcing)
Next by Thread: technical interview of tech writers

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

Sponsored Ads