The platinum rule of technical writing
The act of writing is fundamentally the act of communicating information to someone else. This sounds simple enough, right?
A quick exercise
Pick up a technical article in your field. Or, even better, pick up one in a technical field you don’t know much about. What do you see?
Does the author organize his material in an easy-to-follow, logical progression from background through the technology advancement being discussed and then explain what it all means? Or doe she assume you know all the details and jargon of delay-tolerant packet routing protocols and jump right into the details of RFC 1934?
Are the sentences grammatically correct, relatively easy to read, and written with standard vocabularies? Or do you get lost in sentences that are a paragraph long? Is she so impressed with her own vocabulary of 5- and 6-syllable words that you feel sure she is writing only to convince you she’s smart?
You aren’t writing for yourself
The platinum rule of the written word is that you aren’t writing for you, you are writing to communicate with the reader. Act like it.
Writing in technology—outside of the consumer-level press designed specifically for my mom, generals, CEOs, and eighth graders—is riddled with jargon, complex sentence construction, and words seemingly selected only to amuse budding dictionary writers. Why?
People who write this way are writing solely to convince other people that they are smart, whether they realize it or not. They are not writing for clarity, to share their ideas with others, or to advance technology. They are not writing to communicate.
Complex and “smart” is intimidating
How many times have you read something that was too complex to decipher? You might think that that person is smart, but you probably wouldn’t turn to them for help in a pinch.
At the gut level, you might be too intimidated to even approach them for fear of looking stupid. At a more sophisticated level you might be concerned that you wouldn’t understand the explanation and so asking them would be a waste of time anyway.
Clear and concise makes a connection
Now think about the people and places you do go regularly for help, for example, a particular Web site on network configuration or semiconductor chip design.
I’m willing to bet that the reason you turn to this resource is that its information is concise, clear, and easy to understand, even when the topic is complex. This is one reason that the Dummies books are so popular. Information is presented specifically for consumption by regular people, the non-specialist. There is no jargon (at least not without definitions), and no complex and fancy grammatical structures to hide meaning.
What is there is a single-minded focus on communicating information. And that’s something we’d all do well to stay focused on in everything we write.
