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'
navigators.

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
HDK List MVP
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
msnews.microsoft.com 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
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

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ 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
http://www.raycomm.com/techwhirl/ 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