RE: You Don't Need to Know How

[Ruth Lundquist <rlundquist -at- prosarcorp -dot- com>]

Andrew,

Still I think we vehemently agree.

I don't document complex 3-tier client server claims billing software. I 
have, however, documented complex client-server business applications, 
including AP, AR, GL, reporting and manufacturing modules. In fact, I've 
documented similar systems at 3 different software development companies. I 
haven't a clue how the software did what it did, but I knew in great detail 
what it did. And I knew how to make it do things it wasn't intended to do, 
but was useful in specific businesses. Ergo, I was able to write killer 
docs.

I used a simple stove analogy to make a simple point, which for some reason 
you are unwilling to admit. That is, there are many different types of 
documentation; in fact there is a whole world of it that is much less 
complex than the technical network security systems you work on. It's wrong 
to presuppose that everything that needs to be documented is as complex as 
what you work on & requires the same in-depth technical knowledge that you 
need to do your job.

I'm not arguing that you shouldn't know well the products you document. 
What I am arguing is that not everyone needs to know what you know to have 
successful, fulfilling, and high paying work as a techical (yes, technical) 
writer & to create useful documentation. Alert the media: people have 
different skills & abilities, and different methods for achieving success. 
Have you heard about the Lindberg baby?

As for your assertion that I know how my stove works...well I push a button 
and it gets hot. Is that the type of in-depth technical knowledge you 
propose we all undertake learning? If so, I'm a hell of a lot more 
technical than I thought.

On Wednesday, July 25, 2001 10:54 AM, Andrew Plato 
[SMTP:intrepid_es -at- yahoo -dot- com] wrote:
> "Ruth Lundquist" wrote...
>
> > Completely untrue. I have know idea *how* my double oven with 
convection
>
> > cooking works, but I could certainly explain to anyone how to cook
> > everything from a pizza to a souffle using it. I could tell you how to
> set
> > the delayed timer to start cooking several hours from now, and I could
> tell
> > you how to clean it. I'm a great cook & I'm great at using the oven. 
I'm
>
> > not an engineer & I have no idea how to build an oven or what makes it
> > work. Thus far, it has not been a problem. ;-)
>
> You actually do know how your oven works. You might not know every part
> number and element, but you have intimate knowledge of how it works. Its
> just that the oven is so simple, that you take the "how" aspect for
> granted.
>
> Thus your example is unrealistic. No, of course you don't need to know
> every intimate piece of your watch, a stove, or a VCR.  These things are
> relatively straightforward technologies. Were you documenting a VCR, you
> wouldn't need to know much more than there are heads and motors and
> amplifiers inside.
>
> But what about a three tier client/server implementation for a medical
> claims billing software (I actually documented a program like this once.)
> Do you have even the foggiest idea how this works. Probably not.
>
> Hence the problem. You cannot properly document complex technology unless
> you have some understanding of how it all works. This is fundamental to
> understanding what it does and why it does it that way. Watches, VCRs, 
and
> stoves are terrible comparisons because they're obvious and commonplace.
>
> Most of us do not have the luxury to document commonplace technologies.
> We're working on cutting edge or at least complex technologies and
> scientific information. Yes, if all you do all day is document how to use
> a VCR, you can remain ignorant. But, if you're going to be working on a
> complex new software package, you cannot remain ignorant. You're doing
> yourself, your company, and your readers a tremendous disservice.
>
> Andrew Plato
>
> __________________________________________________
> Do You Yahoo!?
> Make international calls for as low as $.04/minute with Yahoo! Messenger
> http://phonecard.yahoo.com/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


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