Task-based documentation-best practice?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Etienne G is revising documentation to make it task-based: <<some of our
procedure steps can be non-linear and equivalent to: "Use a mix and match
set of tools to do what you want." (Tools being meant as features, objects,
or commands. This could compare to a paint program where the user utilises
the line tool, the paint tool, etc. in any combination to make a picture.)>>

The problem here is that your instruction seems to be too vague, perhaps
because you haven't adequately defined the task to your own satisfaction.
For example, you'd never have both the line tool and the paint tool serving
the same function in a task: one is object oriented, and the other is
pixel-oriented, so you'd probably want a separate task for each option
(e.g., drawing a resizable line vs. drawing a bitmap line).

If you're writing task-based documentation, you must identify very clearly
which tools are most likely to be used or would be most efficient to use for
each task. Once you do that, you can document one approach, and add a note
about other approaches that can be adopted. One thing you might want to do
is write back to us with a specific example so we can help you disassemble
it into more focused tasks.

<<Some of those tools can be quite complex, need few pages to explain, and
include procedures. Obviously, the use of those tools is a fundamental part
of the software.>>

If the tools are fundamental, then one thing you should consider is an
overview section that teaches readers the tool skills they need to use the
program. Back in the dark ages of windowing, manuals included instructions
on how to use the mouse rather than describing how to mouse in each task;
the modern equivalent in software such as Illustrator is a short section on
what the different mouse pointer shapes mean and how to use each type of
pointer in different operations.

<<What is the best way to distinguish between direct "business" tasks and
indirect tasks such as the use of those tools? (In my opinion, this is
important  because the user must focus on the "business" task rather than on
a tool.)>>

A tool is not a task; it's one of the things users must use to accomplish
the task. It's that simple. Drawing a line is a task, and involves a
decision (a discussion fo which line tool to use for each situation)
followed by instructions on how to use that tool. So you might have two
separate sections in your documentation:

1. A section describing the various ways to draw lines.
2. A section describing how to draw something, one step of which involves
drawing lines.

<< ... a large portion of our users cannot rely on anything but printed
books... We can refer to other parts of the documentation but within reason
as it is distracting to continuously being sent from one place to the
other.>>

This reinforces the need to teach the basic tool skills (perhaps via a
tutorial or overview of how the software works) so that readers know the
basics of each tool before they come to each task description. Then,
provided your table of contents and index are well done, it's easy for them
to find the section of the manual that discusses tools in depth so they can
research any advanced features. If you show a basic path through a typical
task, then you can provide concrete details on each step in the task, with a
note that there are other ways to do it. Readers who want to learn those
other ways will look them up; readers who don't, and who just want to do the
task, will follow your instructions and won't need to look elsewhere.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."-Kim Roper 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002. www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.