Re[3]: The Real Offense

Subject: Re[3]: The Real Offense
From: Harry Hager <hhager -at- dttus -dot- com>
To: techwr-l -at- lists -dot- raycomm -dot- com, iluvscotties -at- mindspring -dot- com
Date: 15 Mar 2000 14:22:48 -0600


Scottie,

It's hard to disagree with the points you've made but consider these
questions.

Do you think developers, and no tech writers, wrote all of the Oracle
documentation set written at Oracle?

Similarly, do you think developers, and no tech writers, wrote all the
ColdFusion documents written at Allaire? (To pick two tools we are now
using extensively.)

Again, I generally agree with you. However, in some of my past lives,
I've worked with technical writers who were quite comfortable and
competent when writing about the most detailed of programming
languages or the internals of operating systems. Admittedly, these
people may be few and far between, but they certainly are out there.

You just have to watch out for the imposters. Maybe that's your whole
point.

H. Jim Hager
hhager -at- dttus -dot- com






______________________________ Reply Separator _________________________________
Subject: Re[2]: The Real Offense
Author: iluvscotties -at- mindspring -dot- com at Internet-USA
Date: 3/10/00 10:13 PM


At 03:30 PM 03/10/2000 -0600, Harry Hager wrote:
> Scottie wrote: "Yes, I know that some technical writers write manuals
> for a wide variety of languages, hardware, and software. With rare
> exception, I work hard to avoid buying anything they've written."
> Do you really mean to say that technical writers, "with rare
> exception", are not able to write about "a variety of languages,
> hardware, and software?" And that if you find out a technical writer
> wrote the information rather than a developer, you try not to buy it?

I'm not talking about information or documentation: I'm speaking of
programming manuals -- which are disastrous when written by people who do
not know or use the language, and who have not had their work tested by
people who do.

Having paid $60 (and more) apiece for books containing code that didn't
work, I've become very, very wary of writers who write technical manuals on
a host of languages, software, and hardware.

*USER* manuals would be fine. The technical writer undoubtedly tries what
he's writing about, and confirms that it works and makes sense.

However, programming manuals entail language that is unbelievably precise.
One misplaced colon or space can mean the difference between a module that
works, and one that doesn't. As previously mentioned, a tech writer can
still ensure success by using beta-testers (most of whom will gladly sign
non-disclosure agreements for an opportunity to play with new code).
Unfortunately, however, not all of those who write expensive programming
manuals bother with beta-testers -- and it is very disheartening to spend
so much money, only to learn that the code doesn't work, or that the
approach is all wrong (e.g., the code will work, but entails an
unbelievably inefficient method for that particular language).

By way of example, when Paradox for DOS first came out, a large number of
successful authors of dBase third-party books began writing programming
manuals for Paradox. You never saw such a mess; some code didn't work at
all; some technically worked, but was grossly inefficient (e.g., requiring
two hours for something that should have taken five minutes). The authors'
mistake was that of not having either tried the code themselves, or of
having beta-testers do so. (Any halfway decent Pdx developer would have
spotted the problems a mile away.)







Previous by Author: Re: FWD: Team Leading
Next by Author: ? Edward Tufte Course on Presenting Data and Info
Previous by Thread: RE: The Real Offense
Next by Thread: Re: The Real Offense


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


Sponsored Ads