Latest posts by techwriter (see all)
- What Are the Qualities of a Good Technical Writer? - June 28, 2017
- Be Careful with Humor in Technical Writing - June 26, 2017
- How Much Money Can Writers Make? - June 22, 2017
(Here are some excerpts from Jonah Burke‘s critical and analytical look at the status of technical writing at a Microsoft engineering blog…)
One thing that annoys me about the tech industry is that few techies know how to write. For example, consider the opening sentence from a recent post on the Microsoft “Engineering Windows 7″ blog:
“Certain malware, including the Conficker worm, have started making use of the capabilities of AutoRun to provide a seemingly benign task to people – which masquerades as a Trojan Horse to get malware onto the computer.”
The problems with this sentence are many. Some are grammatical; some are of style; some seem to reveal the limitations of the writer’s brain. Let me address just a few.
First, the subject “malware” disagrees with the verb “have.” I suppose you could argue that malware could be either singular or plural, like “the jury,” but I think “has” sounds much more natural: “certain malware has started.”
If that still sounds odd to you, well, I agree. The reason is that the author anthropomorphizes malware. It’s not the malware, really, that’s making use of AutoRun; it’s the author of the malware. Instead, you could write, “Hackers have exploited AutoRun to install malware on the system.”
My reformulation points out what is probably the most rampant problem in tech writing: verbosity. This author, Arik Cohen, takes a while to get to the point, and his boss, Steven Sinofsky, is no better. It is refreshing to read stuff from guys like Paul Graham and Eric Raymond because they don’t waste your time; they write what they need to, no more.