Machine Design
woman at computer

8 Tips for Technical Writing

Clarity is always king in documentation, whether you’re writing a technical standard or composing a company email. Following these simple guidelines helps to achieve that goal.

Download this article in PDF format.

Checking up occasionally on your writing skills is a good idea. Why? Much of our communication today consists of emails and texts. I don’t know anyone who would say communication isn’t important. If you don’t think it’s important, please leave a comment below. I would love to hear why.

Some of you may have heard that only 7% of the words we use convey a message, and 93% is non-verbal. Many have also debated this fact. No matter what you believe, in the case of emails and texts, you only have text. You cannot convey body language or tone (the 93% of the non-verbal communication). Sure, you could offer a picture or attach a video, but how often does that happen? And how often is the recipient going to open a picture or video?

With this in mind, listed below are eight tips on writing technically in engineering as well as email documents.

1. The Oxford comma: Also known as a serial comma, it comes after the second to last item in a series of three or more. Who cares? Well… if you were wondering what inspired this article, in a recent case, this comma caused a company to lose a suit filed against it.

In short, a document did not include an Oxford comma in a key statement, thus creating ambiguity. This miscommunication led to the company having to pay drivers overtime when it thought the document had covered that fact. The company probably never thought of this particular punctuation when drafting the document, especially considering that the state lawmakers have guidelines for creating such drafts, and they do not include the Oxford comma. So, if you think the Oxford comma is dumb or your state has omitted it from mandating its use, you may want to reconsider.

2. Timeless vs. timely: Depending on the application, it can help to make the writing “timeless” in nature. For example, a standard should be applicable today as it is a year or five years from now. A root-cause analysis or focusing on the foundation of the goal helps achieve this goal. Often, such writing will require time and involve many people impacted by the given technical document pitching in to verify a rule or policy need not be updated every year (unless, of course, that is the plan).

Timely writing is more for emails. Make sure any time you mention a weekday or month, follow it with the exact date. For example, “On Wednesday (3/29/17), we will be discussing the Oxford comma.” While adding the year may not be necessary, I refer you to the Oxford comma. You never know what will come back to haunt you. People are busy, and should not have to look into the detail of your email to figure out if you are talking about the future, present, or past.

3. Eliminating conjunctions: Conjunctions might hinder communication. This may not be the biggest concern; however, it is a technical writing rule. Saying “do not” rather than “don’t” is a formal rule. Abbreviations are okay, but only if it is spelled out previously in the same document (or there is an abbreviation list present before the writing). As you can tell from this article, conjunctions, like using first person, have been lax even in formal writing.

4. Revisions: Include or reference preexisting literature. Include any standard, rule, or other literature that already exists or may affect new technical documents. Technical writing may offer an appendix or a form history, but such documentation is rarely included with emails. Again, everyone is busy, so make it easy for them.

If your email is referencing a past email, or other document, include it in the communication. Do not assume a person will scroll through an email thread to figure out what you are saying. Email threads can become too long for someone to scroll through to find your reference before their next meeting. In addition, some people may not have access to the entire thread, and may not be able to see what you are referencing.   

Don’t forget safety. It is good practice to include any safety documentation associated with what is in the literature.

5. Formal formatting:

            a. Single spaced

            b. There should be a space between paragraphs.

            c. Do not indent paragraphs.

            d. Font size 11

e. The following is not a rule, but some say Times New Roman font is the most legible to read. In general, make sure you choose a font with easy-to-read upper- and lower-case letters.

f. Verbiage, formatting, and captions should stay consistent throughout a document, unless there is a reason for any variations.

6. Learn from metrics: Using white space to help format documents can be pleasing to the eye. This can help prevent overlooking important points. When a document consists of a series of large blocks of text and little spacing, it is easy to skip key points when scanning the file. Even in articles, metrics show that a poorly written article with images and whitespace will perform better than a well-written article lacking these features. 

7. Short sentences: There are no set rules to this one, but people tend to prefer short words and sentences. This tip comes from the prolific author Stephen King, and people seem to enjoy reading his writing.

8. Passive voice: At times confusing for some, this is when the subject of a sentence acts on the verb. For example: “The ball was thrown by the pitcher.” To correct this example, you could say: “The pitcher threw the ball.” Help yourself by taking advantage of technology, and look for a grammar and style check in your word processor.

For Microsoft Word, go to File > Options > Proofing. Look for the drop-down menu toward the bottom of the screen. If you select “Grammar and Style,” it should highlight when you use passive voice. Like spell check, don’t let the computer think for you. To see if it is working, try copying and pasting the two examples in the above paragraph into a Word document. The words “was thrown,” should be underlined in green, and if you right click on that, it should say, “Passive Voice (consider revising).”

Hide comments

Comments

  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
Publish