Say What?

Three simple tests to check your word choice on technical documents

Many elements go into creating a useful, understandable document, but the words you choose are one of the most vital elements of any written piece.  You should never "dumb down" a document in an attempt to make it understandable, but read your first draft and then ask yourself the following questions:

Test #1:  Would your neighbor get it?

Unless you are publishing highly technical research in a highly specialized academic journal, any reasonably intelligent person should be able to understand the basic gist of your document, whether or not he or she is an expert in your field.  Remember that you're not writing to show how much you know, you're writing to communicate. It's still important to use proper terminology and make the document meaningful for your technical colleagues, but be sure to define all acronyms and specialized terms. If what you've written would confuse your neighbor or a colleague in a different field, define, explain, and give examples.  Glossaries, appendices, and sidebars can be helpful for defining terms and concepts without bogging down the flow of the main document.

Test #2:  Does every word count?

When you’re writing a first draft, just get words down on paper and keep up your momentum.  But as you proofread your documents, look for opportunities to clarify your meaning by using fewer, simpler words as long as they are accurate and completely capture your meaning. Trim unnecessary words, such as shortening “it must be noted that” to “note that” and “join together” to “join.” Get rid of meaningless buzzwords.  Don’t ramble in long, complicated, redundant sentences. Get your point across using as few words as possible so you don’t exhaust or confuse your reader. It’s common for a tightened second draft to be half the length of a first draft while getting the point across twice as well.

Test #3:  Do people really talk like that?

Technical documents should have a professional tone and sound as if they were written by relatively intelligent and serious people—a casual "Hey, dude!" tone laden with slang and attitude isn't appropriate.  However, technical professionals tend to go too far the other way, writing text that is unnecessarily stiff, contains vocabulary nobody really uses, and is burdened by unreasonably long and complex sentences.  As you are reading through your first draft, ask yourself seriously, "Who really talks like this?" Most business documents should read more like a letter to a friend (approachable, conversational, relevant) and less like a legal document (painfully formal and arduous to read and comprehend). 

For the ultimate reality check, read the sentence out loud.  If you confuse yourself, run out of breath, fall asleep, or laugh at the ridiculous verbal and mental contortions it causes, it's time to rethink and revise.