Re: Re(2): I'm taking my marbles and going home...

Subject: Re: Re(2): I'm taking my marbles and going home...
From: Andrew Plato <gilliankitty -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 13 Aug 2002 11:16:23 -0700 (PDT)

""Martin R. Soderstrom"" <scribbler1382 -at- yahoo -dot- com> ...

> | Same with programming manuals: If you want to write a manual for a
> | programming language or a fundamental programming tool or non-trivial
> | API, you need to be a programmer; there's just no way around it if you
> | want to create a decent manual.
> That's nonsense. What you need is an understanding of how programmer's
> =think=. Sure, you're going to need some basic understanding of
> technologies and practices, but no where near the depth to which an actual
> programmer would. In fact, that can be a hindrance.

Here we go again...ignorance is a benefit.

Martin, it is absolutely, 10000000% impossible for a human being to write an
authoritative document about a complex technology or programming language without
*some* in-depth knowledge of the topic. In many cases, a good writer must have a
considerably more in-depth and broader knowledge than the SME since they must
integrate these complex concepts with many other disciplines. And the only way
you can do that with ANY degree of success is if you have taken the time to learn
and digest the technology.

Without question, the single largest reason technical documentation sucks is
because the people tasked with producing it relied entirely on the good graces of
engineers who had virtually no stake in the successful execution of that

Perfect example: if an engineer walks up to you and says "our software does not
interface with any kernel level operations." would you have the knowledge to
confirm that? So you slap it in your document and it turns out to be entirely
false. Now your document has a glaring inaccuracy because you didn't have the
knowledge to confirm or analyze that engineer's data. Customers read this and
laugh at it because they know its BS. They throw your product in the trash and
purchase a competitors product.

And since the writer is entirely responsible for the document, this oversight is
squarely the writer's fault. In this example, the writer helped the company lose
a sale because he lacked the ability to analyze the information handed to him for
accuracy and relevance. Sure, the engineer wasn't any help either. But that
doesn't excuse the writer from verifying his sources. A fundamental concept
taught day one in any journalism school.

If you want ownership of your work, you have to have ownership of the knowledge.
Otherwise, you're just editing other people's text, and that isn't writing.

Andrew Plato

Do You Yahoo!?
HotJobs - Search Thousands of New Jobs

Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L.

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!

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 for more resources and info.

Previous by Author: Re: I'm taking my marbles and going home...
Next by Author: Re: Technical editing vs. technical writing (was: playing with marbles, or some such thing)
Previous by Thread: Re: Re(2): I'm taking my marbles and going home...
Next by Thread: Re: Re(2): I'm taking my marbles and going home...

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

Sponsored Ads

Sponsored Ads