ClickHelp Technical Writing Blog
Stories for technical writers, web developers and web designers willing to grow

Good and Bad Technical Documentation Examples

Posted by
Anastasia in Technical Writing on 1/18/20193 min read

Young man sitting on a couch

Are your user manuals good or bad? Let’s run them through our quick checklist. Don’t get discouraged if it turns out to be not perfect, this article contains a lot of ideas to follow that can change your user manuals for the better!

Lists

In bad user manuals, lists of steps for instructions are not-ordered. Simple bulleted lists are used instead. This is very inconvenient to follow such a list when you are trying to use some instruction.

Good user manual always feature ordered lists of instructions. It works great for readers and support engineers as this makes it so much easier to refer to steps when they are numbered. Here’s an article on using lists correctly in technical documents that will help you avoid many common mistakes.

Screenshots and Images

Bad technical documentation has few or next to no images in it. First, this just looks lazy. Second, it makes understanding harder for readers.

Another way to ruin a help topic is to add screenshots/images without proper text descriptions - these are very annoying to decipher.

Good documentation has plenty of images. Any screenshot is always followed by some description. Also, two screenshots never appear next to each other without an individual capture.

It is a good practice to keep in mind the image size (when we are talking about online documentation). Ideally, your images should be of decent quality, but quite light at the same time. Heavy images lead to slow page load and high traffic consumption.

Delivery Speed

formula 1 car

Bad documentation takes a lot of time to be delivered. This can happen due to many factors including the absence of a help authoring tool. Online documentation tools make content creation swift and easy.

Good technical documentation is reusable and takes less time and effort to be created. Taking advantage of a HAT's functionality can be a game changer. Technical writing tools help to organize teamwork, reuse content with single-sourcing techniques, write help topics faster with powerful WYSIWYG editors.

Consistency

Bad user manuals look and feel inconsistent. This happens because often many technical writers can be working on the same project and this can lead to diversity in texts. Like, different terms can be used to describe similar processes, page layouts can look entirely different, etc.

Good documentation teams have a style guide and a documentation plan. These two are used by all team members, and they ensure there are no noticeable differences in style throughout the whole documentation project.

Readability Score

Bad user manuals are hard to read. You really need to put some effort to understand all the terms and break down long complex sentences. Terms are not explained, text contains just a few links/references.

Good user manuals are checked with readability score tools. This means that the content runs through different tests and it gets a readability score based on various algorithms (word length, sentence length, frequency of word usage, quantity of terms in a text). If the score is not satisfactory, user manuals are re-written.

Conclusion

There are many differences between good and bad technical documentation. Often, the devil is in the details and smaller things like poor font choice or too many abbreviations and neologisms or even bad screenshot quality (we are not only talking about their resolution here) can put people off. Feel free to share your ideas on the topic in the comment section below - what bad technical documentation is like for you?

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices

 

HTML Templates for User Manuals
Download Free Templates

Want to become a better professional?

Get monthly digest on technical writing, UX and web design, overviews of useful free resources and much more.
Like this post? Share it with others:
×

Mind if we email you once a month?

Professionals never stop learning. Join thousands of experts subscribed to our blog to get tips, ideas and stories from us once per month.
Learn more on ClickHelp
×
By using this site, you agree to our Security Policy and Terms of Use.     Learn more