[techwr-l] Re: Task Oriented Documentation For Non-Task-Oriented Software

[Chris Kowalchuk <chris -at- bdk -dot- net>]

I liked Steve Jong's distinction between functional and task-based
documentation. It sounds as if Anthony Markatos' software does not lend
itself to either, and that is a pain. I've written for such software
myself, and the company was not willing to spend another dime on
development (at least not anytime soon). As Anthony pointed out, despite
one's best efforts, "it does not make us look good." So we tried our
best to fit square pegs into round holes, and in the end, the
documentation at least allowed the user to navigate the software in
order to perform various tasks, even if the navigation route seemed a
bit convoluted at times.

The reason I mention Steve's distinction, however, is that I think there
can be an important difference between task-based and functional
documentation. If I understand the current wisdom on the subject, there
seems to be a prevailing sense that:
task-based = good
everything else = bad

Now, in Anthony's case, it sounds as if the software were not designed
around any reasonable functional model either, so in such a case, you
are almost forced to use a task-oriented approach to documentation or
you have no context in which to understand or present the software at
all. However, I would like to submit for your consideration, comments,
etc., the heretical idea that the task-based approach is not always the
best or most suitable way to document a product. I think this is
particularly true in situations where you cannot really imagine all the
uses to which the product might be put. When I look at a feature-rich
monster product such as MS Word, I want to know about functions, not
tasks. I can imagine my own tasks, thank you. What I need to know is
whether the software can handle those tasks, and how? Therefore I want
detailed descriptions of the software's functionality. I want to know
the limits of what it can do. I don't need a chapter telling me how to
write a letter; I've known how to do that since I was seven years old.
Although currently decried as a prime example of unusable design, I
actually liked those old WordPerfect manuals that just arranged all
their functions alphabetically. They were complete! If you didn't have
clue one how to use the program, then you could turn to the separate
tutorials booklet. The criticism of the reference manual approach is
that nobody reads them (except me). But is there any evidence that
people read the task-based manuals to any greater extent?

I have to admit, if there is a one-to-one correlation between the task
you want to perform and the task described in the manual, then certainly
the task-based manual is the superior form. And as a tool for learning
about the product's basic functions, the task-based manual is more
accessible. But if you have to derive the information for your specific
task from descriptions of other tasks, or what is more likely, not find
it at all, then surely the reference manual and a good index would
ultimately convey more useful information to more people in a greater
variety of cases. I guess I am not really arguing against the
task-oriented manual, or what might be properly called a user's guide,
but rather am arguing in favour of including in a complete documentation
set the older type of feature- or function-oriented manual, what might
be called the "reference manual" as well. The former is no doubt better
for beginners, but as an advanced user, I become rather frustrated when
I don't have access to the latter. Is there any support left in the
profession for the reference-style manual, or am I howling at the moon?

Chris Kowalchuk


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sponsored by Weisner Associates Inc., Online Information Services
As a leading service provider to technical writers, we are proud to sponsor
TECHWR-L. Visit us at http://www.weisner.com or mailto:info -at- weisner -dot- com -dot- 

Sponsored by ForeignExchange (http://www.fxtrans.com)
Rely on ForeignExchange for responsive and professional 
software localization and technical translation services.

---
You are currently subscribed to techwr-l as: ejray -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-6452R -at- lists -dot- raycomm -dot- com




From