Hindrances for Quality Technical Documents

by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool

“The person who made a mistake and didn’t correct it made another mistake.”


The main goal of any product or company is to reach the customer effectively. This can be done with professional technical documentation, and every company has many technical documents.

Let’s talk about transforming boring technical texts into a reliable and valuable resource to improve the company’s image by avoiding common writing mistakes.

Technical Documentation Pains and Ways to Cure Them

  1. Outdated documentation. Documentation becomes obsolete way too quickly without a plan for updating. Remember this when you make your documentation, and apply a system that is easy to update. You are going to need:
  • A regular update process and schedule
  • A system to track changes. Here’s where ClickHelp comes to the rescue. There is no need to switch between multiple different systems, websites, or files if you have to manage various documents or different versions of the same document.

2. Grammar mistakes. Errors in writing make you seem careless. They can frustrate your readers, and they won’t bother to continuу reading your content. Take care to proofread at least twice to catch common writing errors. And use a grammar correction tool, such as Grammarly — a widely used tool for checking grammar and plagiarism.

3. Contradictions in your documents. That happens when procedures are updated in one place but not another, leading to conflicting and confusing information. Inconsistency is a problem. Such discrepancies occur when different people update the documentation set or use different terminology to describe the same thing. That can confuse the end reader. To achieve consistency:

  • Develop style and terminology guidelines, and follow them
  • Use a help authoring tool to single-source your text, so that a change only needs to be made in one place and it will be automatically updated throughout your documentation set.

4. Flawed structure. If your text looks like a whole endless passage, I am 100% sure that it is a problem to read it. Disorganized, hard-to-find information is a very common problem. If you have a thick binder of operating procedures or a stack of user guides, chances are, no one will look at them. Make your content searchable:

  • Organize topics with clear headings
  • Deliver content in a searchable online format so that people can quickly look up the subject
  • Organize content by user task.

5. Abundance. Like saying something is fairly similar. What is the difference between fairly similar and similar? Sometimes technical writers tend to use long words and phrases in their documents to add value to the text. It affects simplicity. Substitute complicated and long words by their simpler synonyms. Of course, this does not work with specific technical terms.

6. Instructions are hard to grasp. Illegibility leads to a lack of understanding. Make your documentation crystal clear:

  • Use a simple English
  • Explain all jargon and technical terms
  • Get users to follow the instructions and test the procedures.

7. There are no answers to the particular problem. Do you have gaps in your documentation? Identifying such gaps is tricky because you don’t know what you don’t know. Here are some research techniques to discover what’s missing and fill the holes:

  • Test the product to find out what areas haven’t been documented
  • Make a list of all the tasks or procedures your users need to perform and correlate this to the existing content to identify gaps
  • Trouble-shoot your product and watch where they go wrong, as well as what kinds of information they try to look up, then make sure you give them what they need!

The suggestions made here can be used to a good advantage in focusing on the most common problems in technical writing. Practice in recognizing when and how writing can be improved will go a long way toward making you a better technical writer. Most importantly, always consider those who will be reading what you have written and try to make it easier for them to grasp your message.

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors

Content Manager at https://medium.com/level-up-web 👈. I write about web design, web development and technical writing. Follow me on Twitter and Facebook