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

[Odile Sullivan-Tarazi <odile -at- mindspring -dot- com>]

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.


Odile




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