Re: Oh, those tender users (longish)

[Bruce Byfield <bbyfield -at- axionet -dot- com>]

David Orr wrote:
> 
> My job as a writer is to wrest the information the user needs from the
> programmer, who has far more information than the user needs. 

This is one way to do it, and probably the most common way. However,
a writer who already has the information can work faster, and with
fewer demands on other people's time. Also, the more that you know,
the more you can evaluate the information that you're given, and see
what more you need to ask.


> If I don't waste time,
> including listening to technical tangents by programmers, and always pull
> the discussion back to the relevant information, I will get respect.

Personally, I wouldn't want to define irrelevancy too narrowly here.
Some of those tangents may be useful to you later on.

However, tangents can be a problem. If you listen to them, then
programmers may assume that you know more than you do. You may be
put in the embarrassing position of either admitting your ignorance
or listening to long monologues :-)

> Overemphasizing writer technical understanding wastes time, in so far as my
> central job function of communicating with users is concerned. The trick as
> a writer is knowing when I know enough. 

Again, this is one way to do things, and a very common one. But why
assume that it is the only way? I've written at the edge of my
knowledge (the way you suggest) and I've organized my existing
knowledge appropriately for the audience. In my experience, the
second way is far more efficient, less nerve-wracking, and produces
more complete and more useful manuals. 

The first way is documentation triage - work that may be necessary,
but is less than ideal. I understand that, sometimes, I may have no
choice except to work that way. When I do, I take pride in what I
can manage to do under restricted circumstances. But what I have a
hard time understanding is why so many people think that that is the
best and only way to work. I can run a seven minute mile with a
forty pound pack on my back, but I can run a mile in well under five
minutes if I don't handicap myself.

> Writers who feel we have to have as deep an understanding
> of the system as the programmers may be indulging our personal interests
> more than performing the art of technical writing efficiently.

With all respect, I think you're only looking at the short term.
Knowing just enough to write the necessary manual may be more
efficient in the short term. However, if you ever work in a similar
field again, or even if you're simply good at making connections
between different bodies of knowledge, nothing you learn will be
wasted.

Anyway, a bit of indulgence in work-related material can keep you
interested and motivated. So long as the manual is delivered
complete and on time, where's the harm?

-- 
Bruce Byfield, Outlaw Communications
Contributing Editor, Maximum Linux
604.421.7189 bbyfield -at- axionet -dot- com

"The Queen was in her chamber, a-combing of her hair,
There came Queen Mary's spirit and It stood behind her chair,
Singing, 'Backward and forward and sideways may you pass,
But I will stand behind you till you face the looking-glass.'"
- Rudyard Kipling, "The Looking-Glass"

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

          Sponsored by an
 anonymous satisfied subscriber since 1994.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.