Tracking off

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

Okay - since I bear some responsibility for starting this thread and since a
person in private mail has called me "the least informed technical writer in
history" - I guess I should be a wee clearer with my assertions. The JPL snap
didn't clear the tower very well.

Audience is subjective. Accuracy is (mostly) objective. 

Audience is a very debatable concept.  You and I could sit here until the day
God dies debating an audience for a particular document. My beef: Too many tech
writers do exactly that.  They spend hours upon hours obsessing over their
audience when they should be learning about the subject matter. 

Accuracy is a (reasonably) objective, provable concept. 

  The moon is a satellite of earth. 

  The moon is made of cheese. 

One is rather easily proved while the other is just nonsense. Most humans would
agree. Now consider these two statements.

  Readers should understand networking.

  Readers should understand TCP/IP based networking.

Both are RIGHT, but they also could be wrong.  There is no truth or reality
behind each - they are subjective assessments levied by one individual. Highly
debatable and highly argumentative.  

If you can accept that audience is totally a subjective judgement, then the
process of identifying and writing to an audience is practically a no-brainer
in comparison to figuring out how something works. 

Furthermore, nobody is improperly served with too much information. It is
ALWAYS preferable to "over explain" then to "under explain"  You can always
prune a tree, growing limbs takes a lot longer. 

Therefore, I cannot even believe that some individuals are arguing that it is
preferable to "leave out data" for the consideration of the reader.  For all
you know that one chunk of information you left out would have made the
difference between awakening a genius or touching off nuclear war. 

I find it very presumptuous that ANY writer can know an audience so well to
know for certain what the reader does or does not need to know about a topic.  
As far as I am concerned, the reader needs to know EXACTLY what I know. If I
understand the topic - then I can help somebody else understand topic. I need
to impart my knowledge on the reader in a way that makes them understand what I
can understand. 

Therefore, why assume anything.  Why not just hand the reader as much as you
can. You can lead an audience to enlightenment but you can't make them
productive. 

Rather than play up the audience angle, do your audience the biggest favor you
can for them - be a genius about the stuff you're documenting. You'll do a lot
more good to your readers if you have intimate and detailed knowledge of the
subject matter. 

Furthermore, I feel the whole audience angle is WAY overemphasized in tech
writing these days. Yes - you should to consider the people who will read your
stuff - but this is a tiny aspect of writing in comparison to being accurate,
organized, and consistent. In a sense - if you are all these things then
ANYBODY could read your documents and learn something from them. 

If you truly, deeply care about the people who read your documents, you will do
them a favor and be an expert on the topic. How are you doing your readers any
favors by worring about their needs or obsessing over FrameMaker. Nobody will
care if you wrote the doc in FrameWhizzer 2000 for Cray or on the notepad for a
Timex Sinclair if you write the wrong information. 

Lastly, if you truly understand the topic - writing dual and triple track
documentation is a snap. Once you hold knowledge in your head manipulating,
exploiting, leveraging, and condensing that information into bite sized chunks
is a breeze. 

Just think of a topic you love. I'll bet you could carry on a 10 hour
conversation about your hobbies. I could write a encyclopedia about cats -
because I know a lot about cats.  I even know why cats open their mouths when
they smell something good (it?s called flehmenning.)  I could write documents
that address 29,000 different audiences if the topic was cats. 

But if the topic was ground water, ROM code, or how asphalt is made - kick me
to the curb.  I couldn't write a frickin' kindergarten lesson about ground
water because I know absolutely dick-squat-zero about geology. No matter how
long I consternate about my audience, if I have to write about geology I am
hosed until I can become knowledgeable about the topic.  

Now, I think there is some flehmenning cats somewhere that need my love.

Kissy kissy

Andrew Plato
Senior Yossarian / Least Informed Technical Writer
Nately's Whore Consulting, Inc.
"Our clients want to slit our throats from ear to ear in our sleep." 
__________________________________________________
Do You Yahoo!?
Thousands of Stores.  Millions of Products.  All in one place.
Yahoo! Shopping: http://shopping.yahoo.com