Re: Do I have to understand the material?

["Doc" <doc -at- vertext -dot- org>]

Okay Paul, I admit to hyperbolizing a bit to make my point.

But the basic premise is to keep the user in mind. I am not espousing the
"ignorance is good" point of view, I am not against knowing how to code.
What I am railing against is confusing documenting with communication.
Admittedly my main thrust concerned user guides for software since that is
the area with which I am most familiar.

Of course you should understand the material you are documenting, but for
most SW writers what they are documenting is not the code but how the user
will interact with the interface provided to do the job that they want (or
are getting paid) to do.

You are writing for an expert audience that will interpret your notes
depending on their interpretation of the level of understanding of their
audience. Unfortunately in the commercial software business we only supply
this level of interpretation for an additional charge <g>.

I wish I could remember the name of a study that I saw several years ago to
give the following authoritative weight, but I'll have to rely on
anecdotage.

A company I worked for had manuals that were so deeply-based in the
knowledge of the software that the policy was to send a technician with the
software to perform the installation. I interviewed a number of the users
and found that they NEVER opened the manuals. I asked what they used for
reference. I was told that they went first to the training guides, then they
called technical support. "We know," one IT manager told me, "that the
manual will give us a lot of information about how the program works, but
the training guide and tech support will tell us what to do next. That's
what we need."

I'm digressing, sorry.

Obviously there are a lot of different levels of technical writing. Let me
use a simplistic example. If I am stung by a bee my needs are immediate. The
chemical makeup of the toxin is not important to me. That information is
important to the doctor, and to the manufacturer of salves, but those are
different manuals for different user bases. It is the job of the doctor to
understand toxins.

It occurs to me that there is an interesting way to extend this example.

Suppose you are sitting in the doctor's office after being stung by a bee.

Your doctor can't remember exactly what to do and turns to look up bee
stings in a manual.

There are seventeen entries in the index and none are bold-faced or verbose.

The doctor turns to the first entry and finds out that they are of the order
hymenoptera.

The bee sting is starting to swell.

The doctor turns back to the index and looks up bees again.

The second entry says that they live in colonies.

The third entry talks about the uses of pollen as an anti-coagulant in
ancient Maya.

You're getting hives.

The fourth entry talks about anaphylactic shock.

You go into anaphylactic shock.

The fourth entry says that treatment of anaphylactic shock is covered in
Chapter 24.

The doctor turns to Chapter 24 which is 30 pages long ...

The nurse calls 911.

The ambulance takes you to a hospital where they open a first-aid manual.

In the index they find
anaphylactic shock
    allergic reaction   24
    bee sting           24
    sting, bee          24
bee
    allergic reaction   24
    anaphylactic shock  24
    sting               24

They give you an injection.

You go home and continue writing a manual for some investment software.

"I wonder what margin calls are?" you ask yourself.

But the thought passes.

You pick up the next module of code to figure out where margin calls are
placed in the menu structure.

... and life goes on.

-Doc

"Paul Strasser" <paul -dot- strasser -at- windsor-tech -dot- com> wrote in message
news:165621 -at- techwr-l -dot-  -dot-  -dot- 
>
> Doc wrote, in part:
>
> >>>>We don't pick information out of the stack. We find out what the user
> does,
> how the user does it, maybe even why the user does it. Then we try to
> duplicate it using the software or hardware. In other words we stand in
for
> the user, pre-testing the software and trying to fill in the gaps between
> what the programmer did and what the user wants.
>
> We are advocates for the programmer, nor for the code. We are advocates
for
> the product...Our job is to keep the user using the product after they
have
> spent their
> money on it and after they have discovered that the programmers may know
how
> to program and design a glitzy interface but they don't know a damn thing
> about the user's job...
> To do that we don't need to read code, we need to read user's, we need to
> understand their jobs.
> <<<<<
>
> To the extent that you are discussing User's Guides for software, I agree
> wholeheartedly.  The user doesn't give a fig about elegant code.  They
just
> want to get the job done.  One of my jobs here is surrogate user, and "I
> don't get it" is one of my favorite comments to the programmers.  (That's
> said from the user's perspective - I know what the programmers are trying
to
> do, but I want to force the programmers and screen designers to actually
> consider usability every now and then.)
>
> But there's a lot of tech writing out there that isn't for software.
> Letoured's examples were one type.  And I'm working on some writing that
> none of you could write, simply because none of you are experts in this
> area - and expertise is more important than writing style.  These are
> "briefing notes" for naturalists at Old Faithful.  A few folks, including
> yrs.trly., are writing extremely detailed papers about what new
naturalists
> need to know about some of the geysers, so they can impart this wisdom to
> the visitors on nature walks and other visitor contacts.  The briefing
notes
> I wrote for a single geyser complex was over 13 single-spaced pages.  And
> there's one geyser group whose notes are giving me fits - it's so damned
> complicated, and has changed so dramatically in the last few years, that
> I've started about eight different versions of this set of notes.  And I'm
> one of the world's experts on this damned geyser group....
>
> This is stuff you can't fake, can't look up in a book somewhere, or ask an
> SME.  You either know it (via years of field work) or you don't.  In fact,
> this is the sort of writing that will be the "let's look it up" references
> in the future.  Hey, I guess that makes ME the SME.
>
> The fact that my briefing notes for them (done without compensation, if it
> matters - glad to do it) are clever, well-written, and easy to understand
is
> just a bonus :)  They needed geyser experts.  Lucky for them one is also a
> tech writer.
>
> Anyway -- Some of us seem to think that our ability to talk to SMEs, play
> with Google, and are very creative chaps who ask good questions can
> compensate for lack of expertise.  Like I said in an earlier post,
sometimes
> this is true.  But sometimes it's completely untrue, and the ramifications
> can be more dire than something as inconsequential as a naturalist giving
> out inaccurate information in front of a particular hole in the ground.
>
> --
> Paul Strasser
> Windsor Technologies, Inc.
> 2569 Park Lane, Suite 200
> Lafayette, Colorado 80026
> Phone:  303-926-1982
> FAX:  303-926-1510
> E-mail:  paul -dot- strasser -at- windsor-tech -dot- com
>
>
> "
>
>
>



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L. 
http://www.cafepress.com/cp/store/store.aspx?storeid=techwhirl

Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!
http://www.ehelp.com/techwr-l

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