Style and Brevity in steps (long)

[BILL KONRAD <konradb -at- UL -dot- COM>]

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