RE: "Two-track" documentation

[Jason Willebeek-LeMair <jlemair -at- cisco -dot- com>]

Hmmm.  Being technically accurate does not necessarily mean telling the
user everything.  It just means that what you have should be right,
right?  So, in your sort example, if you tell the user to click the SORT
button, and there is no SORT button on the screen (because it is
actually called ARRANGE or something), then you are not being
technically accurate, technically.

J

-----Original Message-----
From: Susan W. Gallagher [mailto:sgallagher -at- expersoft -dot- com]
Sent: Tuesday, December 14, 1999 12:10 PM
To: TECHWR-L
Subject: Re: "Two-track" documentation


Given the comments:
>I always thought the Prime Directive was to write technically accurate
>information in a clear and concise manner. Seeing as how we're
TECHNICAL
>writers and not AUDIENCE writers. 
>
and

>> For the life of me, I cannot understand how audience consideration
>> and technical accuracy are mutually exclusive.
>
and

>Of course, the contrary is the truth. Technical accuracy and audience
>consideration are mutually dependant.
>
>Manifestly, you do not serve any audience by misleading them.

I gotta disagree. Technical accuracy is certainly not the most important
characteristic of technical writing. It has to take a back seat to
relevance
and usability. Sometimes it doesn't even make it onto the bus.

Consider the typical documentation written by the engineer who is
untrained
in writing. Said engineer will go to great lengths to make sure that the
doc is technically accurate. And certainly, a statement like, "this
sorting
routine uses the state-of-the-art, whizzbang sorting algorithm which
allows
you to sort megafiles in a fraction of the time" is technically
accurate.
But does it tell you how to perform the sort? Nope. So, technical
accuracy = 10 but relevance and usability = 0. So what good is it???
Ask the audience. It sucks.

I've even seen times when being technically accurate was a detriment to
the docs because it made the view from the user's perspecitive
excessively
complicated. The user didn't need to know the details to get the job
done.
Those details just got in the way. For example, if the user needs to
sort
the information and the system actually copies the information line-by-
line and then replaces the original text with the new, telling the
truth,
the whole truth, and nothing but the truth may only serve to confound
the
user -- depending on the audience.

So, if the Prime Directive isn't technical accuracy, what is it? To my
mind, it is to support the users in performing their assigned tasks by 
delivering just that information that users need just when they need it.
If we can do all that and be technically accurate too, so much the
better.



-Sue Gallagher               http://pw1.netcom.com/~gscale/susanwg/
sgallagher -at- expersoft -dot- com     http://www.expersoft.com

The _Guide_ is definitive.
Reality is frequently inaccurate.  --Douglas Adams

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based
Help.
More info at http://www.weisner.com/train/ or
mailto:training -at- weisner -dot- com -dot- 

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


---
You are currently subscribed to techwr-l as: jlemair -at- cisco -dot- com
To unsubscribe send a blank email to
leave-techwr-l-19119Q -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.