Monthly Archives: May 2013

Thinking about Writing: Mutilated Metaphors

In this blog, I teach how to use plain language to write clear technical documents. To me, plain language equals good writing. To teach the principles of good writing, I like using examples of bad writing. To do that, I need examples of bad writing, and they aren’t hard to find. Usually, I just have to turn on the TV and watch a few commercials. Here’s one. In a commercial for Lear Capital, which sells gold and silver, the speaker says, “When the government prints money faster than a hungry cheetah, your dollars and paper investments can get eaten alive.” I’m sure the writers thought the hungry-cheetah analogy complemented “eaten …

Continue reading

Posted in Uncategorized.

Rewriting Programmer API Specs: Day 3, The Rewrite

Lately I’ve been blogging about my assignment to rewrite an API spec a programmer drafted. On Day 1, I skimmed the document to assess the content’s (dis)organization. I also read other specs in the document suite to put my document in context. On Day 2, I read through the document, identified and researched unfamiliar terms, and herded similar information together. Now it’s Day 3. Time to start rewriting. My tasks: Turn techie text into user-friendly utterances; add missing information; delete erroneous content. Task 1: Text transformation. When you’re faced with rewriting something, you can do two things: Beat the existing text into submission by editing its very life force, or …

Continue reading

Posted in Uncategorized.