RE: You Don't Need to Know How

Subject: RE: You Don't Need to Know How
From: Ruth Lundquist <rlundquist -at- prosarcorp -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 25 Jul 2001 11:10:23 -0500

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.


Previous by Author: You Don't Need to Know How
Next by Author: Contracting in Vancouver, BC, Canada
Previous by Thread: RE: You Don't Need to Know How
Next by Thread: RE: You Don't Need to Know How


What this post helpful? Share it with friends and colleagues:


Sponsored Ads