Re: The origins of task-oriented writing as a preference

["Mark Baker" <mbaker -at- omnimark -dot- com>]

Mark Dempsey wrote:

> Our management has discovered we need "task-oriented" writing rather
> than "reference-oriented" writing in our manuals.

Be a little careful with the term "task-oriented" documentation. It is often
interpreted as simply meaning procedural documentation. It should, I
believe, be interpreted as meaning documentation that helps people to
perform their tasks (as opposed to documentation that helps them understand
the product.)

The basic idea is that gaining a complete understanding of the product takes
too long to be a practical approach to accomplishing your tasks. Indeed,
complete understanding of the product may not even be sufficient to enable
you to do your tasks. For instance, you may understand internal combustion
and every mechanical system of a car, but still be unable to complete the
task of driving to the grocery store because you lack knowledge of the rules
of the road or the route to the store. On the other hand you can
successfully drive to the store with only enough knowledge of the car to
turn it on, accelerate, break, turn, and fill it up.

For a number of products, writing step by step procedures is the best form
of task oriented documentation. But this only works if the total number of
possible procedures is manageably small. (A road map and a knowledge of map
reading is of more use for the task of getting round than an encyclopedia of
step by step directions (especially since such an encyclopedia would be
almost infinite in size).

I document a programming language. The total number of possible tasks is
equivalent to all the programs that can ever be written. Obviously,
procedural documentation won't work. For a programming language, reference
material is task oriented documentation. Programmers need snippets of
information on particular functions and keywords from time to time.
Reference material supports them in their task in this situation.

For a complex product like a programming language, conceptual documentation
is also necessary for the user to perform their tasks, though probably not
as extensive as would be required to gain complete academic understanding of
the language.

Another approach to task oriented documentation is example based. I am
currently working on a book on internet programming with OmniMark. Every
chapter presents a program that performs a typical internet programming
operation. I then explain how the program works. This book will give
OmniMark programmers a starting point for writing their own Internet
applications. As such it is a form of task oriented documentation. I think
it contains about four procedures (starting the IDE, configuring the web
server, etc.) but it is designed to help users to perform their tasks,
rather than to give them an academic understanding of the language, so it is
task oriented.

So your management is making a false dichotomy. But you may still need to
supplement your reference material with some other form of task oriented
documentation. Perhaps that is procedural. Perhaps it is conceptual. Perhaps
it is by example. Perhaps something else.

---
Mark Baker
Senior Technical Communicator
OmniMark Technologies Corporation
1400 Blair Place
Ottawa, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com
Web: http://www.omnimark.com