Tips and Tricks: 10 Heuristics for Evaluating Documentation Usability

Tech Writer Today’s Technical Writing Tips and Tricks column is brought to you by Adobe Systems, Inc. Download a 30-day free trial of Adobe FrameMaker here.

documentation usabilityWe 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 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.

Ena Arel

Ena Arel is passionate about Information Architecture and Content Strategy. Ena’s expertise is in developing Web Help UI designs, content models, and taxonomies, and re-engineering authoring and output generation processes. She is adept at deriving requirements from diverse stakeholders, balancing these requirements with waste-reduction strategies, and evangelizing the evolving information architecture and strategy to the organization. Ena has an M.S. in Physics.

Read more articles from Ena Arel

Try Doc-To-Help Today