Re: Task Oriented Documentation For Non-Task-Oriented Software

[SteveFJong -at- AOL -dot- COM]

Anthony Markatos <tonymar -at- HOTMAIL -dot- COM> asks an excellent question: "[I]f the
software was NOT designed task oriented, can the end user
manual be written in such a fashion?"

He goes on to explain that for the software he is documenting, "the
lack of task oriented design [is] glaringly evident. The documentation
actually prompts the end user to ask the question 'Why do I have to do so
much jumping around between menus to accomplish a given task?'  This does
not make us look good."

First, to review, task-oriented documentation describes not the *functions*
of a product, but the *tasks* that can be accomplished with it--not what it
does, but what you can do with it. The two are not synonymous, which is why
technical specifications are not the same as user documentation (and thank
goodness for that!). Sometimes, as in the case of Anthony's product, the
divergence can be significant. Powerful tools can be like that--the uses to
which they can be put far exceed their functions. (Think of compilers.)

My first reaction is that for such a product, a simple functional
description, such as one might write as a reference manual, won't work,
because there's no connection between a function and a task, A task-oriented
user's guide is critical. Without task-based information, users may well not
be able to use the product at all. In this case, the value of user
documentation is especially high. So YES, you can write the book, and you
must!

My second reaction is sympathy for Anthony's plight; the documentation may
well "show up" the engineers. But that's also to the good. When you have to
walk through a series of menus to accomplish a task, the software is
difficult to use. (The common task of turning on and off "smart quotes" in
Microsoft Word is a good example: it takes several menus, and is not widely
understood.) Was it the company's intention to product difficult-to-use
software? Probably not; so if the documentation makes it plain to management
that difficult-to-use software is what they've got, you are doing the
company
another, greater service.

In the early Nineties, I worked at a company for which we used task-based
documentation on a complex module of a large network management system. We
(well, the writer, and I as lead writer) documented the tasks of this module
so clearly that management could see it was horrible software, and they
canceled its release as part of the whole system. One manager said, "We
don't
have to show the world that [we've] entered the Seventies." I think we did
our company a favor. You may be able to do the same for yours.

That's what I think, anyway. What about you?

          -- Steve

=========|=========|=========|=========|=========|=========|=====
Steven Jong, Documentation Team Manager ("Typo?  What tpyo?")
Lightbridge, Inc., 67 South Bedford St., Burlington, MA 01803 USA
mailto:jong -at- lightbridge -dot- com -dot- nospam          781.359.4902 [voice]
Home Sweet Homepage: http://members.aol.com/SteveFJong

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=