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.
Ensuring that Technical Documents Are Easily Understood
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
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.
Likewise, sentences that are too short can be bothersome to the reader. Get to your point. But don't cut up the information. Short is as bad as long. It sounds choppy. Sentences that are less than seven words, unless used to emphasize a point, begin to sound childish. Instead, focus on saying what you need to say in perfect, bite-sized chunks.
Avoid Unclear References
I think the words 'it' and 'thing' should be banned from the English language. Okay, maybe that's a bit harsh, but consider how many times you've gotten messages that say something like this: 'Look at the drawing in the manual and evaluate it to see if the thing is too confusing.' By 'it,' is the writer referring to the manual or the drawing? Is the drawing or the manual confusing, or just the sentence?
Using a pronoun (it) to refer to two different subjects (drawing and manual) can be very confusing to your reader. To fix this type of unclear reference, replace the word 'it' with the actual word you intended 'it' to replace.
For the sentence I provided, you could write, 'Look at the drawing in the manual and evaluate the drawing to see if it is confusing.' or 'Look at the drawing in the manual and evaluate the manual to see if it's confusing.' Both are correct, which should reiterate the need to make your references clear. Clear references will ensure that your reader knows exactly what you are referring to and what you want him or her to do.
Choose Words Wisely
For like, the past few years, like I've really noticed that, like everyone seems to really like the word 'like.' It's as if we've all morphed into valley girls. I think what has really happened is that we've gotten lazy with our use of language. As a result, we use the same word over and over and over again.
It may not always be the word 'like.' Even as I write about technical documents, I find that I have to be vigilant in making sure I don't overuse the word 'document.' But one great benefit of the English language is that there is at least one similar word or synonym for just about every word we have. For example, when talking about technical documents, I might reference them as technical writing, technical communication, information, data, or any number of other words that still clearly express my meaning.
Don't be afraid to look up synonyms for your words. Varying your vocabulary prevents the document from becoming monotonous and will keep your reader's attention. Likewise, try to stay away from repeating the same phrase or starting sentences in the same way. People say variety is the spice of life - so to spice up your writing, choose a variety of words to get your message across.
Lesson Summary
It is vital that the technical documents we create are easily understood by our readers. We can accomplish this clarity by doing the following:
- Writing well-formed sentences
- Keeping sentences an appropriate length
- Avoiding unclear references
- Choosing words carefully
By constructing sentences carefully and choosing words thoughtfully, we can ensure that our writing meets the needs of our audience. Documents that are easy to understand help save time and money in the business world.
Learning Outcomes
After you've reviewed this video lesson, you will be able to:
- Recall the importance of writing technical documents so that they are easily understood
- Describe four ways to provide clarity to technical documents
To unlock this lesson you must be a Study.com Member.
Create your account
Register to view this lesson
Unlock Your Education
See for yourself why 30 million people use Study.com
Become a Study.com member and start learning now.
Become a MemberAlready a member? Log In
Back