Guidelines for Technical Writing Learned the Hard Way From Many Great Editors

I’ve been writing technical books, feature articles and columns for more than 40 years. Based on the old guideline, “An expert is someone who’s made all the mistakes possible,” I am well along my way to being an expert.

Most of my writing has been for a general engineering audience, written in readable prose, rather than for a peer reviewed technical publication, written in “high technish”. While I always enjoy getting feedback from readers, the most valuable feedback I have gotten has been from my editors, especially those at Prentice Hall. These folks see a lot of pieces and can clearly articulate what works and doesn’t work.

Over the years, I’ve collected the guidelines and advice passed along to me from my editors and dedicated readers which I think about constantly when I write. Writing is a process. The more you practice applying these guidelines, the faster you can accelerate up the learning curve.

In the interests of passing along to others the great help I’ve received from experts in my career, here in one place are the top ten most important guidelines.

1. You can never be too unambiguous- do not assume the reader understands what you are saying.
2. Use every opportunity to teach the reader your specific nuances and specialized vocabulary that you want them to learn
3. At the point you lose someone, you have lost them for the rest of the article. Start at ground floor and build up complexity as you go. Lead up to the most complex topics and use visuals and imagery where possible to make clear the points.
4. Always start at the end. Ask, what is the most important take away(s) for the piece. Focus on these. After the paper is written, ask, for each word, does it support the take away you want. If it doesn’t, take it out. It’s how a sculptor carves an elephant from a block of stone. He imagines the elephant and cuts away everything that is not elephant.
5. A key message for all successful products is that they help the user get to the correct answer faster. This is one of the elephants. Use every opportunity to illustrate and emphasize how a product or tool helps the user get to the correct answer faster.
6. First drafts can be backstories to help you articulate the details and the story. After you write the first draft, “re-write” (not edit) to emphasize the key points (the elephants).
7. Avoid the “novel” version of how you got there, unless that is the key take away.
8. The more technical the content, the shorter should be the paragraphs
9. You should be able to tell a parallel story in pictures and figure captions that a reader can use to skim the article
10. While you tend to think of every word as a cherished child, never hesitate to kill off your children when they don’t add to the elephant.

Good luck in your writing adventures!