This primer on technical writing was published by Digital Equipment Corporation (DEC) in 1976. At the time, they faced the challenge of explaining how to use a computer to people who had never used a computer before. All of the examples are from DEC manuals that customers failed to understand. I found the entire book delightful, insightful, and mercifly brief. The book starts with a joke, which I’ve copied below:
On the West Coast they tell the story of a plumber who started using hydrochloric acid on clogged pipes. Though he was pleased with the results, he wondered if he could be doing something wrong. So he wrote to Washington to get expert advice on the matter. In six weeks he received the following reply:
“The efficacy of hydrochloric acid in the subject situation is incontrovertible, but its corrosiveness is incompatible with the integrity of metallic substances.”
The plumber, who was short on formal education but long on hope, was elated. He shot a thank-you letter back to Washington. He told them he would lose no time in informing other plumbers about his discovery. Five weeks later he got another message:
“In no case can we be presumed responsible for the generation of pernicious residues from hydrochloric acid, and we strongiy recommend, therefore, than an alternative method be utilized.”
The plumber was delighted. He sent his third letter in the next mail. In it, he said that about 15 plumbers in his city were now using hydrochloric acid for pipes. All of them liked it. Now he wondered whether the good people in Washington could help him spread the news of his discovery to plumbers throughout the country. At this point, the correspondence fell into the hands of a rare Washington bureaucrat—one who knew how to write to plumbers. Within a week the plumber was reading these words:
“Stop using hydrochloric acid. And tell your friends to stop too. It eats the hell out of pipes.”
Certainly the letters in this interchange are a far cry from technical writing. Nevertheless, they offer a lesson to the new technical writer: Write so your reader can understand.
I’d like to share a book recommendation:
“Writing for the reader”
by O’Rourke, 1976
https://archive.org/details/bitsavers_decBooksOReader1976_3930161
This primer on technical writing was published by Digital Equipment Corporation (DEC) in 1976. At the time, they faced the challenge of explaining how to use a computer to people who had never used a computer before. All of the examples are from DEC manuals that customers failed to understand. I found the entire book delightful, insightful, and mercifly brief. The book starts with a joke, which I’ve copied below: