How Not to do Tech Writing

rogersgeorge on February 8th, 2018

I dare say this Boomerangs comic speaks for itself…

Do I need to belabor the point? Tech writing should be so plain and clear that you don’t notice the writing! Send for that five critical techniques for good writing document I mention in the column on the right if you don’t believe me, or if you want some good advice.

Subscribe to this blog's RSS feed

Tourette Syndrome

rogersgeorge on July 27th, 2016

When people read good expository writing, they think about the content, not about the writing. (This doesn’t apply to poetry, by the way, where part of the attraction is admiration of the writing itself.) In a way, this is a disadvantage for technical writers and such, because by definition, then, you tend not to notice the good stuff. Several years ago someone got a Nobel prize in economics for describing this situation, in which the highest value things tend to be under-priced because the purchaser tends not to appreciate the difference in quality.

Tourette syndrome is a condition when a person with physical tics involuntarily inserts profanity into their conversation. That’s the point of this Carpe Diem comic—the fortune teller has Tourettes. I suppose the comic censors prevented the cartoonist from making her say anything more profane, though “serial killer” is bad enough.

Carpe Diem - 07/15/2016All that leads to a hobby horse of mine that I’ve mentioned only once before. You don’t need profanity to explain something. It calls attention to the writing, jolting the reader away from the content. If you’re a tech writer with Tourette syndrome, be sure to proofread your work really really carefully.


Interesting use of “technical writer”

rogersgeorge on November 29th, 2013

A recent article in The Register criticized Google’s Eric Schmidt for, among other things, his (lack of) ability as a technical writer. Since this blog is mainly about expository writing, of which technical writing is a subset, I feel a need to share. Here’s the passage I’m referring to:

…Schmidt goes on to show he’s not conversant with the gentle art of technical writing with procedures that use inconsistent verbs, fail to open each step of a procedure with an active verb and make assumptions that lead to user-befuddling ambiguities.

Gentle art, eh? I’m flattered. Eric’s instructions are too long to quote here (you can find a link them in the article), but the criticisms mentioned in the quote above are worth noting for your own writing.

Inconsistent verbs…active verb. I’m not sure what the writer is referring to here, but when you write instructions, you should use the imperative. Do not say “Please.” Give one instruction per step. Tell the result of following the instruction correctly. (Do not write the result as a separate step!)

User-befuddling ambiguities. Ambiguity is the bane of technical writing. You should write so your material is interpreted exactly one way. Have someone follow your instructions. If they get something wrong, fix the writing. Do not whack the person upside the head for being stupid.

Tech writing has a lot more features, and I saw several other tech writing mistakes in Eric’s material, but I won’t go into them here.

Now in Eric’s defense, he is not a technical writer. He’s an extremely successful businessman with lots of money. (Warning: shameless plug ahead) If his intent is to write a good set of instructions (and not a marketing piece disguised as tech writing) maybe he should hire (ahem) a good technical writer to write the instructions for him.

Google's Eric Schmidt

Eric Schmidt. Image credit: AP