Tips and Tricks: 10 Heuristics for Evaluating Documentation Usability

We aim to produce documentation that is useful to users. That is, we want our users to find the right topics and use them to achieve their goals with the software. I use ten documentation usabilityDocumentation Usability heuristics, or rules of thumb,  to design, evaluate, and course-correct technical content before the ship date. Using these heuristics can help content developers catch most structural errors, and provide insight into the actual user experience with the documentation.

The Documentation Usability heuristics in this article were inspired by the ten general principles for usability design, developed by Jakob Nielsen and Rolf Molich in 1990. However, I had to adapt many of them based on my own experience with evaluating documentation usability.

Preparing for the Documentation Usability Evaluations

Before evaluating your documentation, choose a user goal that you know many users will want to achieve with the software. It’s a good idea to ensure that this goal, while realistic for typical users, also aligns with the organization’s goals for the product. For example, the user goal a company that produces modelling software, might be “I want to model a controller.”

Start the software. Then, perform the tasks just as the user would while using the documentation. You may also choose to enlist one or more peers to do the evaluation. Because your peers are likely to be less familiar with your documentation, they can represent typical users more effectively and better simulate the users’ experience.

Heuristics for Evaluating Documentation Usability

Use the Documentation Usability heuristics to evaluate your experience in accomplishing a goal, in the same manner that users would to complete a task using the software. For each heuristic, be sure to capture specific areas that were challenging, site examples, and explain why they were challenging. Capture your observations of the tasks users tried to complete, their feedback during and after, and accompanying screens. Also, capture the areas that were easy and trouble free so that you preserve what works well during any rework.

1. Search and navigation

Users should be able to find the topic using search, or by browsing to the topic. If more than one topic is required, users should be able to navigate to the next topic with ease.

2. Orientation

Users should know at all times where they are in the documentation relative to the whole, and relative to where they were previously. Provide topics to help users orient to thought processes and complex tasks.

3. Decision making

Users should be able to choose the appropriate topics, decide what inputs to provide the software, and interpret their results.

4. Task completion

Users should follow an efficient path through the topics in the documentation to accomplish their goals.

5. Task generalization

Users should be able to extrapolate the information in the documentation to situations that are not explicitly documented. For example, they should be able to determine what inputs are appropriate for various applications.

6. Diagnosis and recovery from errors

Users should be able to learn how to diagnose a problem, correct it, and possibly prevent it in the future.

7. Match between documentation and the real world terminology and concepts

The documentation should use language and concepts that are familiar to users, and avoid software-based terminology.  Incorporating key words that typical users would search on is critical.

8. Minimalist writing

Topics should avoid information that is irrelevant. Every extra unit of information in a topic competes with the relevant information, which diminishes the findability of relevant information.

9. Consistency and standards

Users should not have to wonder whether different words, situations, or actions mean the same thing. It adds to cognitive load and detracts from their ability to quickly complete the task. Follow platform, software, and domain conventions.

10. Integration with software

Users should not have to exit their software workflow to access documentation. Provide search access to documentation from the product and context sensitive help, where possible.

Tips and Tricks: 10 Heuristics for Evaluating Documentation Usability | Technical Communication India |

12 years ago

[…] Interesting link about document usability   […]

Larry Kunz

12 years ago

Thanks, Ena. This is a good list. In fact I’m going to recommend it to the students in the Tech Comm certificate program in which I teach.

With the exception of #10, the list is equally good for all subject-matter areas. Not just software.


12 years ago

Heuristic analysis of a documentation is a post action. During heuristic analysis, we find usability issues in the documentation. Correcting those changes in the documentation become a huge task, time consuming, and cost incurring.

So it is better to follow usability principles for the documention from the concept stage. We should treate the documentation as a product, and apply the usability principles.

Here is what we can do:

1. Understand the application and the business – Learn the domain – so that it is easier to document.
2. Define the business goals for creating the documentation and ensure these are acheived once the documentation is done.
3. Check for technological Constrains, if any – for example, platform dependency of the Help files.
4. Check for the Marketing / Branding goals – For example – whether the template is in line with the marketing/branding policy.
5. Create a User Profile – this includes environmental profile and persona (persona is created when the real end-user is not available around). For example, if the application caters more specifically to senior citizens (say, an insurance policy application for senior citizens), such users would require bigger fonts in the documentation; and so on. Similarly, if the application is mobile gaming, so you know it’s more youth specific – in such a case, you may use a few bright fonts/ colors.
6. TOC/ Content Organization – logical flow
7. Usability Testing – This is most important – this helps us to know the specific difficulties the user might encounter while using the document. Ideally, list the most general tasks, and allow the user to find help for. Note the difficulties that the user encounters, and correct the documentation accordingly. Also, note the tasks that the user could easily navigate to, so that you know what works.
8. Implement the findings of the UT.

I am sure, you all can add to this.


12 years ago

Ejaz, you are right on. Heuristic principles are also design principles. It is best to design with them in mind and then evaluate against them.

Tips & Tricks: 10 Heuristics for Evaluating Documentation Usability | technical communication |

12 years ago

[…] Using these heuristics can help content developers catch most structural errors, and provide insight into the actual user experience with the documentation. The Documentation Usability heuristics in this article were inspired by the ten general ….  […]

Советы и хитрости: 10 способов для определения пригодности документации | Разработка технической документации

11 years ago

[…] Источник: Tips and Tricks: 10 Heuristics for Evaluating Documentation Usability […]

Subscribe to TechWhirl via Email