Re: Style and Brevity in steps (long)

[Kelly Holmes <kelly -dot- holmes -at- NATINST -dot- COM>]

We like to avoid using a lot of words and just show the user what they need to
select. Here's how we would explain opening the Windows 95 Device Manager:

To open the Windows 95 Device Manager, complete the following steps:
1. Select Start>>Settings>>Control Panel.
2. Double-click on the System icon.
3. Click on the Device Manager tab in the System Properties dialog box that appears.

It's a simple example, but here's our reasoning:
* In #2, we *could* say "...in the Control Panel window." But if the user has
followed #1, the Control Panel has freshly appeared on his/her screen; it's obvious
that after we told him/her to open the Control Panel, s/he should find the icon in
the Control Panel.
* However, in #3, the user now has 2 windows that we have instructed him/her to open.
So it might not be clear where s/he should look for that tab. 95% of the users,
however, will realize that they should look for the tab in the dialog box that we
*just* told them to open. Therefore, the location goes after the action, and only as
a reference to avoid confusion.
* The ">>" is a bad approximation in email, but it's very effective on paper. It's
actually Alt-0187 in the Times font. Windows 95 menus (the Start menu especially)
involve a lot of selections one after the other. So, it's good to have all the
selections in close approximation, without extraneous wording.

My two cents,
Kelly
--
Visit Kelly's Scrumdiddlyumptious Scrabble Site
http://www.geocities.com/CollegePark/2639/index.html



Please respond to konradb -at- ul -dot- com

To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
cc:    (bcc: Kelly Holmes/AUS/NIC)
Subject:  Style and Brevity in steps (long)




I know these topics have been discussed before, and I've gotten a lot of
info from the archives, but I'd like to throw the question out in a
slightly different form than I've seen before.
In procedural steps, should you indicate WHERE an action occurs before the
action?
We use a general style of beginning each step with an action word except
when there are conditions affecting the step, in which case we put the
condition first.
However, I'm encountering resistance to the idea of also putting LOCATION
before the action when it is significant for performing the action.
For example, I would prefer to write:
To add a new vendor:
1. From the Go menu, select Administer Procurement.
Result: The Administer Procurement window appears.
2. From the Use menu, select Maintain Vendors, then select Identifying
Information and an action of Add.
(Note: Step two describes sub-menus or fly-out menus that only appear after
you select the first item.)
This makes sense to me in that the information is presented in the order
that it is used or processed by the reader.
However, others here would prefer to ALWAYS put the action first except for
conditional steps.  Right now, I'm not completely certain how they would
write the above steps.  Probably something to the effect of
1. Click on Administer Procurement from the Go menu.
Result: The Administer Procurement window appears.
2. Click on Maintain Vendors from the Use menu, then click on Identifying
Information and Add.
(And yes, they deliberately prefer "click on" to simply "click" or
"select")
Similarly, many of the steps consist of telling the user to complete a
labeled edit field or select from a labeled option group or drop-down list.
 In many cases, it is sufficient to simply write something like:
9.      Complete the distribution line information:
        -       Enter or verify the Amount for the distribution line.  The sum
of the distribution lines must equal the amount on the parent voucher line.
        -       Enter the Account.
        -       Enter the Dept.
        -       Enter the Location.
        -       Enter the Project Number, if appropriate.
        -       Enter the File Number, if appropriate.
        -       Verify that GL Unit is USA.
In the above list, the item to be entered corresponds to the label on the
panel and they are entering this information from an document.  (And I just
realized that these appear to break the rule about conditionals first--but
in this context, it should be obvious to the users whether a Project Number
or File Number is available to be entered.)
However, sometimes we need to specify exactly what they should enter in a
field, as in entering sales tax:
3.      Complete the distribution line:
        -       Enter or verify the total sales tax in the Amount for the
distribution line.
        -       In Account, enter 12329.
        -       Leave Dept blank.
        -       In Location enter COR.
        -       Verify that GL Unit is USA.

Here, we specify the account number they should enter.  Others here would
probable rewrite the second item about as
        -       Enter 12329 in Account.
and the fourth as
        -       Enter COR in Location.
Note that the labeled fields from the GUI are bold-faced in the
documentation and the literal text is in a fixed-width font, New Courier.
Does anyone have opinions about which approach is preferable.  In
particular, I'm hoping to gather some rationales to argue for putting
location first, when indicating specific information.
Also, in some tasks, the user is only completing a limited number of
controls in the GUI. For example, in a section on entering non-standard
payment terms:
4.      To specify due dates:
        -       Change the Due Date Control to User.
        -       In Due Date, enter the date payment is due if no discount is
taken.
        -       In Discount Due Date, enter the date payment is due in order to
receive the discount.
Where Due Date Control, Due Date and Discount Due Date are the labeled
items the user needs to change.  There may be other controls which they do
not change for this particular task.  The others would probably write:
4.      To specify due dates:
        -       Change the Due Date Control to User.
        -       Enter the Due Date.
        -       Enter the Discount Due Date.
(Note--yes the omission of explanatory information is deliberate--they seem
to come from a school of thought where brevity is valued above all
else--they would argue that descriptions of these fields are available in
reference information for the panels and repeating it here is
redundant--even though I have argued that users will quickly abandon the
documentation if they need to constantly flip back and forth between
various sections to find what they need to know.  In some versions of the
documentation, the steps were primarily what I consider "monkey
steps"--where the step simply reiterated the label on the GUI and told the
user to complete it or enter it or choose it without any explanation at all
of what the option or field meant.  I'm still fighting to provide the user
with the information they need within the steps to complete the task at
hand, even if it does result in the steps being somewhat longer.  They
really seem to have an aversion to lengthening the steps.  As side note, I
just barely got them to agree to allow us to use articles in the
steps--previously they would remove all articles and, what they deemed to
be, other unnecessary words.)
I realize I've probably broached several issues here with a single salvo.
To summarize, I think their basic position is that they want to keep as
short as possible.  My position is that if we want people to actually be
able to use the steps, we need to provide more contextual information to
help them understand what the step means.  I don't mean to include
essay-length overviews with each step, but rather some cues to make it
easier for them to perform the step without having to refer back to other
sources.  Related to this, I feel the information in steps should presented
in the same order that it is processed by the user--meaning that you
sometimes need to specify location before the action.  In this case, I
think breaking the pattern of Action first makes it clearer that they need
to do something special in the location.
Any opinions on this are welcome. (Note, I get TECHWR-L in digest, so I may
not reply immediately.) TIA.
Bill Konrad
Phone (847) 272-8800 ext. 41886
konradb -at- ul -dot- com