Re: Task vs. Procedure query

[Fred M Jacobson <fred -at- BOOLE -dot- COM>]

Ronald L. Stone writes:
> ...
> An example of documentation focused on _task_ would be:

>    Set the _User Name and Server_ (located in the _Setup_ menu).


> An example of documentation focused on _procedure_ would be:

>    Open the _Setup_ menu and set the _User Name and Server_.

> ...

Ron-

I have a different definition of task-oriented documentation.  My goal
is to describe the various tasks my users must perform using task-domain
terminology.  That is, I want to tell them how to do what they need to
do using language they already understand.  I may have to introduce some
new language if the software (in my case) requires it.  I may have to
explain what the required tasks are and why they are important (for
example, in a System Administration manual).  But, given that, my task-
oriented Sys Admin doc (to use the example) should cover tasks like
adding a new user and backing up disks.

It may be useful to create a hierarchy of tasks, but at the bottom I
put the procedures.  Procedures are based on a well-defined set of
assumptions about what the user can do.  (You can think of these as
prerequisites or lower-level procedures.  They probably appear somewhere
else in the documentation.)  I assume that the reader of the procedure
knows how to navigate the menus and complete dialog boxes.  This defines
the vocabulary for the procedures.  (Of course, the user may not arrive
the procedure by working through tasks, he or she may remember what
procedure to perform or may arrive via a hyper-link.)

Now to actually address your question (I think).  I prefer to mention
menus, menu items, dialog boxes, fields, and other interface object as
well as any other "things" involved in the procedure in the _same_order_
as the user uses them.  So, I like what you term "documentation focused
on procedure."  I might write a procedure like this:

    To set the user name and server:

    1.  From the _Setup_ menu, select _User_Name_and_Server_.

    2.  Enter the ...

    3.  Click ... to make the change.

I actually prefer a "shorthand" way of writing menu selections (especially
when there are nested menus):

    1.  Select _Setup_|_User_Name_and_Server_.

I'm not certain what punctuation is right to separate the levels of
selection.  I've seen or tried "|", ">", and "->".  The FrameMaker4
manual uses ">" to name commands, but uses "Choose ... from the ...
pop-up menu" in procedures.

Maybe I've addressed your question.  In any case, I hope this is of some
use.

-Fred
--
INTERNET: fred -at- boole -dot- com          PHONE: (408) 526-3292  FAX: (408) 526-3055
USPS: Fred Jacobson / Boole & Babbage / 3131 Zanker Road / San Jose CA 95134