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