haynes@ucbarpa.Berkeley.EDU (Jim Haynes) (05/09/89)
In article <1323@lzfme.att.com> jwi@lzfme.att.com (Jim Winer @ AT&T, Middletown, NJ) writes: > >2. Technical documentation for products is abysmal (sp?). This >seems to be a result of several factors (I do this for a living, so >I'm qualified to comment): > > * The original documentation is done by engineers and the >Journalism or English majors who serve as technical writers don't >actually understand the technology. This triggered me on a funny story that I've been meaning to post to comp.misc as part of the ongoing "Computer Folklore" topic. One of my summer jobs in between college (electrical engineering) was to complete the technical manual for a certain piece of equipment. I was given the first draft, which had been written by the engineer who designed the equipment. He had then left the company and gone to work for another. Now I have a lot of respect for this fellow's engineering design ability; but his writing skills are something else again. In a purchase specification he wrote "... These parts will not be supplied by the supplier." and one of his transistor circuit descriptions said "the signal is basically applied to the base." Most of the manual was a lot worse than this, so I wound up practically rewriting it from scratch, using his draft just to help my own understanding of the logic diagrams. After he had been at his new job for a while he sent us a postcard with the text "Hi. I'm having an enlightening affair at [company X]." This was stuck on the department bulletin board for quite some time; I think it was sort of a contest to see if anyone could figure out just what he was doing out there. One of the secretaries occasionally was known to fly out to Albuquerque and meet him; but if she knew what an enlightening affair was she wasn't telling... haynes@ucscc.ucsc.edu haynes@ucscc.bitnet ...ucbvax!ucscc!haynes "Any clod can have the facts, but having opinions is an Art." Charles McCabe, San Francisco Chronicle