Good and Bad Technical Documentation Examples

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

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

 

 

Source: https://medium.com/level-up-web/good-and-bad-technical-documentation-examples-bce3353cbc08

Written by