Proofreading Your Technical Documentation
I watched TV the other day and saw a misprint in the news reporting. The news ticker announced that some “terrorist” recorded a new album. Since when these people are into music? But then it hit me — it was the “tenorist” who was presenting the new jazz album.
I remembered one laugh getter that happened to me with one of my documentation projects. I created a manual with the following wording: “When somebody gets overboard, shoot!” Just one letter wrong, and the meaning changes dramatically (it should say “shout,” not “shoot” I’m a peace-monger after all). It’s a good thing that it was the first draft, and I had an editor.
Proofreading is essential for technical documents. Just as all software requires testing and checking software for bugs, technical writing also needs rechecking to ensure that the quality of data written in the technical documentation is not compromised.
What is Proofreading?
Proofreading is defined as correcting different errors in writing, such as grammatical stuff, spelling checks, punctuation, technical arrangements, and other verbal communication mistakes. This is done before the text is published or shared.
Proofreading correctly isn’t as easy as it might first seem. You’re constantly fighting with your eyes and brain, both of which want to tell you that everything on the page is just fine (remember my failure with people “shooting”). The pick of a person for doing the proofreading thing differs for every team. In theory, it is the role of a responsible person to allocate this task. People best suited to proofreading are eagle-eyed and have a comprehensive grasp of punctuation and grammar.
Usually, professional writers are involved in proofreading their technical documentation or articles without others’ prior help. But it is a difficult task to proofread your own work, though.
Proofreading is needed to:
- ensure accuracy and consistency
- go through each word and not sentences
- maintain the professional reputation
- make the last adjustments before publishing.
It is hard pedantic work that can be exacting, tiring, and repetitive.
Best Proofreading Tips
- Take a Break
This tip is known to everyone. If you try to proofread right after you finish your document everything will appear exactly as you expect it to. It’s all our brain tricks. So rest a bit, switch to a completely different task, and better yet leave it overnight. Then come back to it with a fresh eye.
2. Prepare yourself
Speaking of fresh, aim to proofread at your best working time — mind your circadian rhythms. Make sure you have everything you need at hand. A list of what to look out for, a style guide (if your company has one), and the right technical writing tool.
3. Be systematic
Filter through the text line by line. Go through the document once for sense, a second time for technical accuracy. In case of a short document read it backward to better spot typos.
4. Read the document aloud
Read the document out to yourself in some quiet corner of the office or better do it at home. You’ll trip over the awkward bits in a way that you didn’t when simply tracking the words in your mind, and you’ll notice missing or extra words. It will be even better if you ask someone to read the text for you or use text-to-speech technology.
5. Don’t miss anything
Give special attention to title pages, headings, subheadings, subject lines — it’s too easy to assume that there couldn’t possibly be mistakes in the large text. But that’s where overlooked errors will howl the loudest.
Be careful around line endings too — it’s surprisingly easy to miss words repeated at the end of one and the beginning of the next.
6. Know the common troubles
You should be aware of the repeated errors and be ready to catch them. Once you’ve been proofreading for some time, you may start your own list. For now, here are some common mistakes to keep your eyes ready for:
Grammar
Matching verbs and subjects: the verb or “doer” in the sentence should be in the correct form (singular or plural) to go with the thing doing it.
Company names are typically treated as singular but not always, so check your organization’s style guide.
Punctuation
Common missteps include:
- unnecessary, missing or misplaced apostrophes
- inconsistent hyphenation
- mixing up hyphens and dashes
- punctuating incorrectly around brackets.
Of course, you can use spelling and grammar checkers but never assume they are faultless. Continue to look out for misspelled words and homophones, which sound the same but spelled differently.
And if you know you have your own blind spots, keep a list of those.
7. Look over structure
If you don’t use special help authoring tools, you may also need to pay attention to the layout and formatting of the document. MInd things like:
* captions — are they on the right items?
* the contents page — do headings/page numbers match the actual copy?
* consistency of style — bold, italics, etc.
* page numbers and other footer or header material — check they are accurate and in the correct order
* headings — check the relevance and for repetition, and that the heading levels are correct and consistent
* numbering — check the sequence.
8. Don’t forget the little details
Besides looking for typos, incorrect or missing words, dodgy punctuation, and suspect grammar, give the facts a final checkup.
Are the decimal points in the right place? Have you written millions where you meant billions? Have you spelled the customer’s name right?
We are humans and tend to make mistakes. That’s why we cannot manage without proofreading. The good news is — proofreading is such a skill that you can develop. The more you proofread, the sharper your eye will become.
Stay well!
Amrit.
“Follow the river and you will get to the sea.”
