Task-based documentation-best practice

Subject: Task-based documentation-best practice
From: etienneg -at- interlog -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 28 Feb 2002 09:16:42 Canada/Eastern

I am analysing our set of documentation for re-architecturing. This set of
documentation has evolved over the years with new releases and a couple of
change of format and it is time to review it on a "zero-based" basis.

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 different
kind of users and reference guides.

My understanding of task-based documentation is that it should follow closely
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 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.) 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.

My questions are:
Where does the documentation of those tools belong?
? In the reference material (including their procedures in task-based format)
? 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 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.)

I should mention that a large portion of our users cannot rely on anything but
printed books. This excludes the use of hyperlinks. 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.



---------------------------------------------



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.



Follow-Ups:

Previous by Author: Release Notes
Next by Author: Importing XML into FrameMaker+SGML
Previous by Thread: RE: How to keep a senior manager busy for hours on end.....
Next by Thread: Re: Task-based documentation-best practice


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


Sponsored Ads