Seven rules for technical writing

If you are a professional working in a technical or scientific field, you will eventually have to write.  Whether it is reporting on your research, describing a process or system, or justifying some engineering decisions, these documents are the concrete evidence of your professional skill.  Here are some tips on doing it well.

1.  Acronyms are not your friends.

When you finish your first draft, review it for the number of different acronyms you used.  How do you know if you’ve used too many of them?  Try this simple test. Count how many different acronyms you used, then find your total in the categories below.

0-1 total acronyms: You’re fine.  Good work!
2-5 total acronyms: If any of them are used three or fewer times, turn them back into words.
5+ total acronyms: Turn half of them back into words.  No one will notice.

Now that you have a reasonable number of acronyms, are the remaining ones defined the first time you use them?  Never assume the reader knows anything beyond what last year’s intern knew.  You can safely assume they have most basic technical knowledge, but that’s it.  Writing that you “completed COTS C&I NDEs” isn’t a space saver, it means you spilled your Alpha-Bits.

While we’re on the topic, define acronyms only once. You know that guy at the party who has had a couple too many, and is now telling the same story over and over, even to the same people? That’s redefining acronyms; don’t be that guy.  Every time you tell the reader – again – that the Widget Contracting Officer (WCO) controls the widget contract, they sigh and wonder if they can excuse themselves from the conversation.

2.  Jargon isn’t your friend, either.

This is especially common when the person writing is “in the field.” I’m not saying anything against those in construction, not even field engineers.  It’s natural to write with the words used to accomplish the work.  That said, it is important to realize that your readers are almost invariably in a different field.  The budget review team neither knows nor cares what an “overpack” is if you can’t take the time to explain it – in two sentences.  They just know that these “overpacks” are $700,00 over budget for the fiscal year.

While we’re on jargon, never say things like “submitted for issuance.”  Adjectives and adverbs like “issuance” makes my skin crawl.  Instead say “submitted to be issued.”  Passive voice isn’t bad, especially when it’s replacing fake verbs.  If the passive tense bothers you that much, shorten it to “submitted.”  This leads to the next piece of advice…

3.  Don’t try to use “big words.”

There will be someone reading your document that knows you’ve used a fancy word wrong, misspelled it, or even made it up.  Shakespeare and Dodgson may have made up words, but they knew they were doing it.  Most importantly, they didn’t intend to write something else.  “Frugal” and “chortle” are one thing; “refudiate” is something else entirely.

4.  Use the right words, not the words everyone else uses.

Some words are commonly confused for others that may sound similar.  These malaprops can make you look foolish, communicate the wrong meaning, or weaken the point of your writing.  Or all three.

The parts comprise the whole; the whole is composed of the parts. Don’t say that “Three managers, two experts, and a government representative comprised the team.”  Either “the team was comprised of” those members, or the members composed the team.

Another one is less and fewer.  Fewer compares a number of items or units; less provides a comparison within a single unit.  There are fewer leaves on the lawn this Fall.  The weather was less windy last year.  It doesn’t matter if the Speedy Checkout says “Ten Items or Less” and has said that since 1976.  It’s still wrong.

I’ve tried to get writers (especially engineers) to stop using impact when they mean affect, but it seems to be impossible.

5.  Be very careful with numbers.

Whether they are written as digits or spelled out, numbers can cause problems.  It is even more important than with text to ensure they are accurate; spell check alone will not be enough.  Verifying your numbers is the difference between “eight-inch pipe” and “eighth-inch pipe.”

6.  Be even more careful with “find and replace.”

Never use the “replace all” option unless you are absolutely certain you mean it.  Even then, check.  I bought a replacement power supply for a computer recently.  In the manual, it referred to “indiviDL” units or some such.  I’m guessing “DL” is the term used for “dual” throughout their product line, and the guy writing the manual did a global replace and didn’t proofread.

7.  The “enter” key is your friend.

Some folks still call it the “return” key.  Whatever you name it, it is your friend.
Just because you’re still writing about the same “ion extraction process” or what have you, that doesn’t mean it belongs in the same paragraph.  Paragraphs are a way to divide up the text by subject, by thought, or into related groups.  Think of it this way: the reader gets a chance to mentally blink at each comma and inhale at a period.  Paragraphs let the reader look away from the page, think about what you’ve written, and check themselves for understanding before moving on.

Paragraphs give an expected level of organization to writing, no matter how formal or informal. If you want your writing to be clear and understandable, you’ll make that half-page block of text into at least three paragraphs.

Technical writing can be daunting.  It can also be frustrating to have the project’s edit staff bleed all over your report.  I can’t guarantee that the editors won’t continue to rip your report to pieces; but if you can keep this advice in mind, at least the pieces will be bigger.

Advertisements