Re: Style and Brevity in steps (long)

[Lizak Kristin <LizakKristin -at- JDCORP -dot- DEERE -dot- COM>]

Bill - I always indicate where an action occurs before the action itself. In
my business, I am writing to farmers - some who may have never used a
computer before. I always write an introductory paragraph explaining what
they are trying to accomplish, and any background info they need. Then I
outline the steps so the user can actually follow it as they read.

> -----Original Message-----
> From: BILL KONRAD [SMTP:konradb -at- UL -dot- COM]
> Sent: Monday, June 08, 1998 1:28 PM
> To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> 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
>
> ~
>