Ensuring that Technical Documents Are Easily Understood

Lesson Transcript
Instructor: Suzanne Sweat

Suzanne has taught 12 years in the NC Public School System and three years at Campbell University. She has a master's degree in English Education.

Clarity in technical documents is paramount in communicating what the document is trying to teach an audience in the way of information or protocol. Learn more about the importance of making technical documents easily understandable and four ways to write with clarity. Updated: 10/31/2021

Insufficient Instructions

Screams of profanity jolted me from my afternoon nap. My usually calm, cool, and collected husband was attempting to put together a computer desk, and apparently, it wasn't going well. As I gently tiptoed around the pieces to see if there was anything I could do to help, my red-faced husband yelled, 'Yeah, you can teach people to write! This doesn't make any sense.' Apparently, the person responsible for putting together the instructions for our new desk didn't learn the important lesson of making instructions easy to understand. And my husband was paying the price.

Whether it's writing an end-user document or an email to a colleague, ensuring that technical documents are easy to understand is paramount to having a successful business. You want your readers to know what you're asking them to do, and you want them to do it right. Not providing well-written information will lead to frustration, inaccuracies, and potentially a loss of revenue for your business. In order to make your technical documents easy to understand, follow these guidelines:

  • Write well-formed sentences
  • Keep sentences at an appropriate length
  • Avoid unclear references
  • Choose words carefully

An error occurred trying to load this video.

Try refreshing the page, or contact customer support.

Coming up next: Sequence in Technical Documents

You're on a roll. Keep up the good work!

Take Quiz Watch Next Lesson
Your next lesson will play in 10 seconds
  • 0:01 Insufficient Instructions
  • 1:12 Write Well-Formed Sentences
  • 3:26 Keep Sentences an…
  • 4:44 Avoid Unclear References
  • 5:48 Choose Words Wisely
  • 7:07 Lesson Summary
Save Save Save

Want to watch this again later?

Log in or sign up to add this lesson to a Custom Course.

Log in or Sign up

Speed Speed

Write Well-Formed Sentences

Let's start with understanding how to write well-formed sentences. Making sure that you follow conventional grammatical rules is key to helping people understand what you are trying to say.

Imagine getting an email from your boss that says something like this: 'The presentation after the meeting on Tuesday.' Would you know what your boss expects? Of course not! This sentence is missing a verb and a complete thought.

This type of grammatical mishap is more likely a result of rushed writing rather than a lack of knowing how to write. So, the first step to ensuring that your writing is easily understood is to proofread your work. You can avoid making major grammatical mistakes by reading over your document carefully before you send it, or better yet, have someone else read over your work.

In addition to making sure that you follow basic grammatical rules, you should also follow basic grammatical structures. Switching traditional grammatical structures in technical writing can be very confusing for your audience. Yoda speak does not a good sentence make. Though writing in this manner may provide a creative element to your writing, not everyone will understand how to transpose the words into the correct order, especially if you are creating an end-user document for a customer in another country. Stick to the traditional subject-verb-information syntactical structure for most of your sentences.

Another grammatical issue, often seen in writing, is the overuse of punctuation marks, specifically the comma, which can be overwhelming, especially in a long document. Forget the lie that you were told in elementary school that said to put a comma every time you pause in your reading. There are specific rules for when a comma should or shouldn't be used. If you find that you use more than two commas in a sentence, see if you can rewrite the information so that you break the sentence into two or more ideas.

If we naturally pause in our reading when we see a comma, then the reader of the sentence on the screen took five breaths while reading that one sentence! That could cause hyperventilation! Other than the overstated health risks of too many commas, it just makes the writing sound choppy. So, use the comma sparingly to keep your sentences flowing smoothly.

Keep Sentences an Appropriate Length

Another way to help your documents be easily understood is to be mindful of the length of your sentences. Sentences that are too long or too short can distract the reader. Sentences that are long make it difficult to remember important information.

Think about it this way: Before cell phones, if you asked someone for his or her number, you had to be ready to remember those digits because chances are you didn't have something on which to write it down. Phone numbers are short; ten numbers if you include the area code. Our short-term memory can handle that. But what if phone numbers were 20 digits? Our limited memories would struggle with that much information. Sentences are the same way! You want to provide information in small chunks, so that the brain can more easily process and remember the data. Strive to keep your sentences between ten and fifteen words. Anything much longer should be broken into two or more sentences.

To unlock this lesson you must be a Member.
Create your account

Register to view this lesson

Are you a student or a teacher?

Unlock Your Education

See for yourself why 30 million people use

Become a member and start learning now.
Become a Member  Back
What teachers are saying about
Try it now
Create an account to start this course today
Used by over 30 million students worldwide
Create an account