Re: Documenting wizards that have numbered "steps" - LONG

Subject: Re: Documenting wizards that have numbered "steps" - LONG
From: Odile Sullivan-Tarazi <odile -at- mindspring -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 2 Jun 2005 10:08:01 -0700

FWIW . . . (first stepping back to consider the larger context, including how, why, and to what extent we document wizards)

In our product, we document tasks and we document the UI.

Wizards themselves, as part of the UI, are doc'd with context-sensitive (F1) topics, one per page. Each F1 topic lists every control on the wizard page, in an order that mimics the page, and provides a brief explanation of what the user does with that control (enter such and such, select to . . ., click to . . .). Following this opening imperative is any additional info the user ought to know about using the control -- dependencies, gotchas, and so on. The default value for the control, where it pertains, generally closes the entry.

That's the ideal, at any rate.

The procedures document how to use the UI to get something done, so any given window, dialog, or wizard might make its appearance anywhere within the procedure, depending upon the flow of work in the UI. Other than in simple cases, the procedure rarely maps simply to walking through a dialog or wizard. It generally begins with locating and bringing up the dialog or wizard, for one thing. But many of our procedures are fairly complex, directing the user in and out of several dialogs or wizards, often stepping through other portions of the UI as well. If you think in terms of documenting the task -- and this is in response to the "why document the wizard" pov, not to the original question regarding steps -- I think that incorporating use of the wizard into the task makes good sense.

We try to keep our procedures lean, directing users into the F1 help for finer-grained detail. The F1 topics are there for the user who wants further information either on the use of a control or on the larger context of using that control. (This is assuming that we've gathered all the info there that we would like to see gathered there.) Users who can find their way around the UI on their own and who can figure out, for the most part, what they need to do without further support are free to do so. Users who can find their way around the UI on their own, but who might need or want a little more background on using that UI, have it right there at their fingertips with the F1. Users who need help locating dialogs and wizards, and users undertaking complex tasks which involve moving in and out of lots of different portions of the UI, can locate the guidance they need in the procedures. When all works as it ought, and we've time to get all the info in, of course.

We try to keep procedures reasonably compact, breaking them into smaller chunks (and individual topics) when necessary, so that complex procedures are often nested. This sort of nesting works well with online help. It might be tricky in print doc.

In terms of stepping users through the wizard, our wizards have both a page title and a step number in their title bar, and in procedures we refer to the former: "On the such and such page of the such and such wizard" (at first reference to the change of location in the procedure), "On the such and such page" (in subsequent references). We have dropped the response line following the step in which the user first launches the wizard, the line that explains (in a paraindent) that the such and such wizard appears (or opens or is launched or is displayed). We instead indicate the change of location in the step following the first appearance of said wizard.

But even were you to use the step reference alone (rather than a page title) to indicate location in the wizard, what would it matter that your steps and the wizard steps do not map one to one? Why not --

1. Go to [do you use that construction?] such and such and log on.
2. Navigate [do you use that verb in the procedures?] to . . .
3. In the such and such dialog, change the such and such option to . . . and change the path name to . . . [or select the option, enter the path name, whatever fits the controls in question]
4. From the main menu, choose such and such. [menu selection to open wizard, yes?]
5. On the Welcome page of the such and such wizard, click Next.
6. On step 1 of the wizard, <select, click, enter . . . whatever> and click Next.
For more information at any time, press F1 or click Help from within the wizard.
7. On step 2, <select, click, enter . . . whatever> and click Next.

Of course, my context may be so different from yours that what works for us, in terms of referring to wizard steps, may not apply to your doc at all.

In terms of the larger debate, how and to what extent we ought to document the UI, including wizards, no doubt other factors pertain: the complexity of the product, the background and expectation of the users, the uniformity (or not) in background of the users, the type of documentation, and so on. What I have briefly outlined is the approach my group has adopted. I'd be curious to hear how other groups are handling it.


At 10:36 AM -0600 6/1/05, l_migliorini -at- yahoo -dot- com wrote:

I am curious to know how others handle the following situation.

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.

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.

I thought of having the main procedural steps and then treating the whole wizard as just one step. That way the discrepancy between "my" numbers and the "wizard's" numbers would not be so great:

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.
5. do the next step of the main procedure once done with the wizard
6. save and close and so on.

What do the others think?


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: Print-quality Icons (WAS: symbolize roles)
Next by Author: Almost definite joinups
Previous by Thread: Re: Need your help to face an Interview
Next by Thread: Transitioning Text Across Platforms

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

Sponsored Ads