Guidelines for Easy to Understand Technical Writing

Tweet

Where did techies learn to write?! I like mysteries to have twists and surprises; I like novels to develop character and place; I like biographies to delve into history (actually I don’t like biographies). But I don’t want technical analysis or product descriptions to meander, use vague, ill-defined terms or stick to generalities. Tech blogs and articles need to get to the point.

There are plenty of bad examples out there from a myriad of independent blogs to some of the comments posted to widely read blogs. Rather than focus on the bad examples I come across daily doing research, here are two of my favorite good examples of technical writing:

David Pogue in nearly any of his blog posts http://pogue.blogs.nytimes.com/ lists what he does and doesn’t like in clear terms. He even wrote a whole post on tech terms he avoids (http://pogue.blogs.nytimes.com/2008/10/16/tech-terms-to-avoid/#more-560 ) .

Wired Magazine, http://www.wired.com/wired/ , consistently publishes clear articles. Not only do they use understandable prose, they have outstanding graphic artists who create charts and diagrams that intrigue anyone who loves visualizing data.

Granted Pogue and the Wired Magazine writers are paid to write, so they have an economic interest in writing well and have had a lot of practice. Still with a few simple precepts, even a geek with limited linguist ability can make his or her point more effectively.

Three guidelines:

1. Give specific examples
2. Only use terms that are well understood by your readers
3. Use bullet points and lists wherever possible, or at least introduce your points with terms such as first, second and third.

I will try to keep all three in mind before my next post or technical comment on a Pogue column.