TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re[2]: The Real Offense From:Scottie Lover <iluvscotties -at- mindspring -dot- com> To:techwr-l -at- lists -dot- raycomm -dot- com Date:Fri, 10 Mar 2000 17:00:37 -0500
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.)
