RE: Task-based documentation-best practice

Subject: RE: Task-based documentation-best practice
From: "Steve Hudson" <cruddy -at- optushome -dot- com -dot- au>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 1 Mar 2002 19:32:56 +1100

Lateral thinking for one second (and probably obtuse for that as well), it's
exactly the same issues that are being explored by the 'breadcrumbs'

Personally, I write User Guides (cum help systems) and Tutorials.

However, come P&P time, I write instructions and procedures generic to
several processes. I then refer to them from our processes as
'single-sourced' (in a limited sense) information.

In the same way, task based-guides are really a linear tutorial. Modern
techniques make it easier to branch your doco as required (two topics
leading on to their respective links via x-refs) to follow whichever path
the user follows.

HTH, the overly-simplified _writer_,

Steve Hudson - Word Heretic, Sydney, Australia
For Questions regarding MS-Word please use the MS news servers or a mailing
list in preference to heretic -at- tdfa -dot- com -dot- Ideally, post to and send me an email to go answer it.

PS: <stitch> New sig as a result of the Free Advice thread :-)

-----Original Message-----
From: etienneg -at- interlog -dot- com
One of the mandated direction is to move closer toward a task-based format.

The new set will probably consist both of task-based guides for the
kind of users and reference guides.

My understanding of task-based documentation is that it should follow
the "business" tasks that users perform to fulfill their responsabilities
with a
linear format such as this:
To do abc:
1) do xxx
2) do yyy
3) do zzz

with xxx, yyy, and zzz being either procedure steps or subtasks.

My difficulty is that 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
features, objects, or commands. This could compare to a paint program where
user utilises the line tool, the paint tool, etc. in any combination to make
picture.) Some of those tools can be quite complex, need few pages to
and include procedures. Obviously, the use of those tools is a fundamental
of the software.

My questions are:
Where does the documentation of those tools belong?
? In the reference material (including their procedures in task-based
? In the task-based guides (even if the use of the tool is not a direct
"business" task)
? Somewhere else: a "tool" section or guide

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

I should mention that a large portion of our users cannot rely on anything
printed books. This excludes the use of hyperlinks. We can refer to other
of the documentation but within reason as it is distracting to continuously
being sent from one place to the other.

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.

Have you looked at the new content on TECHWR-L lately?
See and check it out.

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 for more resources and info.

Previous by Author: Re: When Programmers Design Web Pages ...
Next by Author: RE: Are you a writer
Previous by Thread: Re: Task-based documentation-best practice
Next by Thread: TECHWR-L Premium Jobs, Events, and Announcements

What this post helpful? Share it with friends and colleagues:

Sponsored Ads