Technical Writing: Weaving the Silk Purse

Abstract

The problems with flawed technical documents are frequently problems of a larger nature. When the subject to be described is itself amorphous or internally illogical, technical writing may only dutifully reproduce the inherent confusion. Writers should be alert to identifying these problems and assisting product/procedure designers in eliminating confusion at its source.It's no secret that customers frequently complain about programming manuals. In annual meetings, around the office coffee machine, in comp centers neath the abend's red glare-one can hear the people who depend on software documentation raising agonized cries. The problems that can be found in manuals are many, and familiar: minor irritants like Ted Mack spelling, blunders like lost table headings or illegible printing, yellow-brown fogs of vagueness, absent examples, missing information, even the deadly sin of downright factual mistakes-all these flaws are not uncommon.There have been attempts at solutions. Originally, back in the Iron Age of data processing, manuals were written by the same people who designed the systems, by programmers and engineers. It was soon concluded that the manuals were turning out badly because-although these fellows were marvelous coderrthey were *