Re: Messages. . .and new thread: Moving to process-orientation

[Fred M Jacobson <fred -at- BOOLE -dot- COM>]

> Now I'd like to add a new topic to the fire. I'm interested in finding
> out how other writers have made the transition from writing feature-oriented
> software documentation to process-oriented documentation. When an
> application is extremely complex and there are multiple ways to accomplish
> the same task, it can be difficult to work in every feature that
> is related to a particular process. Is it our "duty" to use every single
> feature that is documented in a reference manual in a corresponding
> process-oriented users manual, especially when some of the functionality
> is redundant and would cause confusing lateral offshoots in an otherwise
> linear and iterative process flow? (redesigning the product is not an option)

> Thanks in advance for your input.

> Lisa Kaytes
> (lisa -at- warren -dot- mentorg -dot- com)

Lisa-

I spent a number of years as a technical instructor, trainer, and
training developer before I worked as a technical writer producing
"documents." Technical training tends to be very process-oriented:
When the students complete the training they should be able to do
something they couldn't do before.

In the documentation sets I have used and worked on, process- or
task-oriented material is usually some type of "guide."  The
documentation often also includes a "reference," either on paper or
online.  In _this_ situation, the guide need not be comprehensive.

When the product provides _n_ ways to do something (where _n_ is
large), the guide should describe the simplest (that is,
easiest-to-understand) method.  (Here I state the unstated implication
of your final parenthetical comment:  Designers and engineers sometimes
produce over-complex systems, perhaps because they, or their market
research sources, have not spent the effort to understand how potential
users do or should use such systems, perhaps because they do not want
to choose one possible way of doing something believing that there are
potential customers that prefer different ways, and perhaps because
they must or feel they must continue to add features to the product.
Then they ask us to produce clear and simple documentation.)

To document alternate methods, more general, more efficient, or just
different, the guide can take one or both of two approaches.  One is to
describe the alternative briefly and point to the reference
documentation.  The other is to provide a simple and complete guide to
all the tasks required to use the system (a first pass) as well as
additional treatments of more advanced alternatives.  In general, you
may need to visit a topic or task a number of times.  This method is
sometimes called the spiral approach.  (Think of the spiral going up
and expanding as it comes around to a topic again and again.)

-Fred
--
INTERNET: fred -at- boole -dot- com           PHONE: (408) 524-3292  FAX: (408) 730-0558
USPS: Fred Jacobson / Boole & Babbage / 510 Oakmead Pkwy / Sunnyvale CA 94086