Re[3]: The Real Offense

[Harry Hager <hhager -at- dttus -dot- com>]

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