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

["Chris Despopoulos" <cud -at- ARRAKIS -dot- ES>]

Allow me to blaspheme...  Sometimes task orientation is NOT
the best option... Perhaps???  Just a thought.

Now for the blather....

For a sufficiently complex system, there is usually a need
for tutorials, task oriented documentation, and encyclopedia
or dictionary-like documentation.  I believe this is
especially true for combinatorial systems, where the
"interface" is more like a grammar than it is like buttons
and dials.  And I submit that the primary goal behind GUI's
was none other than to provide an interface that approaches
grammar.  The old menu-driven interface (for those old folk
who can remember the days) provided a command for every
activity.  For example, a move command, a copy command, a
delete command, a format as bold command, a format as italic
command...  all of which entered the user into different
"modes" for selecting, then executing.

A GUI has nouns, verbs, and modifiers.  You have gestures
for declaring a noun (select something), and then a list of
applicable verbs (cut, copy, paste) or modifiers (bold,
italic).  By making a grammar of combination, the actual
number of terms is reduced without reducing the number of
things a user can do.  In fact, the advent of GUI's has
spelled disaster for Q/A...  Software still defines a
finite-state machine, but for practical purposes, there is
no way a Q/A team can test or analyze results of every state
in a big enough piece of software.   Hence we all find more
opportunities to complain about bugs.

Likewise, it is at least *possible* that documentation could
never anticipate every procedure a user might imagine.  And
in fact, task orientated docs usually spell out
representative tasks, leaving it up to the user to combine
them into meta-tasks, or to use them as models for less
representative tasks.

"Get real," I hear you say.  Alright, one system
sufficiently complex to render task orientation questionable
is the English language.  This system is fraught with
documentation...  Tutorials (basic grammar), encyclopedic
reference (thesauri), dictionaries, theoretical works
(advanced grammar, philosophy of language), pedagogy, etc.
Far and away, the most used documentation is the dictionary.

Where does that leave the tech writer?  I believe that for
sufficiently complex sysems, he should provide more than
task oriented user docs.  Just an opinion, and not a contest
winner...  For FrameMaker, I designed a help system (version
4.0) that was basically a dictionary...  If you could click
on it, you could get a description of it.  I arbitrarily
categorized the subject matter (assuming myself a subject
matter expert), and provided an overview at the head of each
category.  The judges for a documentation contest had only
one thing to say about it...  "Not task oriented!"  Well,
undaunted, I still believe in providing various orientations
for documentation.  Of course, as a contractor, I have yet
to be hired to provide anything but task orientation.

But for the original poster, I submit that perhaps a
"tutorial" (in quotes because it might cover procedures well
beyond what people usually expect in a tutorial) AND a
functional reference might be in order.  And maybe the
interface seems so complex because the software is so
complex...  Who knows.  I'm not about to slag the engineers
for crappy design until I see the software and sit in the
design meetings.

cud



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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