Major documentation mistakes | Are you making them?

Do you want to leave your users feeling confused and frustrated? Writing great documentation can be an uphill battle if you aren't aware of the pitfalls. Success depends on teaching the many skills consumers need to develop to become adept users of your products. Here are some common mistakes to avoid when writing your documents.

System based documentation

Be wary of documenting product features instead of tasks. Your users don't want to know to function of each component of your product. Instead, they need to know how to use these many components to complete actual tasks.

Often system based documentation is the result of engineers and developers providing content. Their job is to build features into the product, so it is only natural that they would write details about individual features. It is your job to take these detailed specs and incorporate them into procedures based on the tasks users need to perform with the product.

Lack of context

All procedures in your user guide should begin with a description of any prerequisite steps necessary for completing the procedure. For example, telling a user to click a button on a dialog is useless if they cannot find the dialog. You can use cross referencing if necessary to point them to any prerequisite instructions, but make sure the user has sufficient context necessary to successfully complete the task.

Poorly balanced content

Consumers will not all have the same goals when they read your user guide. Some will read the guide from front to back to develop detailed product knowledge before they start using the product. Others will use the guide as a reference tool, reading only the sections that they don't understand through intuition. You need to write with various types of readers in mind.

Be sure to include overview information and best practices for users who want to become experts. Also include reference information and granular content for users who are trying to troubleshoot a specific issue, or complete a single task. Try not to make assumptions about your audience; instead, base your content decisions on usability studies, personas, and actual data so that you meet the needs of all users.

Outdated or incomplete content

Schedule periodic reviews of your user guide, so that the developers can update any outdated content or fill in missing information. Products change; your documentation should change accordingly.

By scheduling regular reviews, you decrease the risk of misleading users. Providing inaccurate or incomplete documentation can destroy the credibility of your guide or even put consumers in danger.

Inconsistent structure or presentation

Presenting information in a consistent manner allows users to absorb content more efficiently. By establishing style and formatting guidelines and following them strictly, you help to reduce reader confusion.

Be sure to use styles to control the formatting of your paragraphs and headings. Also, present your chapters in a structured manner. Each chapter should be introduced and concluded in a similar way, so that the reader feels a sense of familiarity and comfort with the presentation of content.

By following the tips above, you should have a better chance of producing a helpful user guide. Try to stay focused on key tasks and on understanding your audience.

If you enjoyed this post, you might also like User guide writing tips.