Ena Arel, Ayantek
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. This article proposes ten Documentation Usability heuristics, or rules of thumb, which Content Developers can use to design, evaluate, and course-correct technical content before the ship date. Using these heuristics can help to 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 19901, however I have adapted many of them based on my own experience evaluating documentation usability.
Preparing for the Evaluation
Before evaluating your documentation, choose a user goal that you know many users will want to achieve with the software. For example, consider that users “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 may better simulate the users’ experience.
Use the Documentation Usability heuristics to evaluate your experience in accomplishing a goal, which users should be able to complete using the software. For each heuristic, be sure to capture specific areas that were challenging, site examples, and explain why these areas were challenging. Also, capture the areas that were easy and trouble free so that you preserve what works well during any rework.
- 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.
- 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.
- Decision making Users should be able to choose the appropriate topics, decide what inputs to provide the software, and interpret their results.
- Task completion Users should follow an efficient path through the topics in the documentation to accomplish their goals.
- 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.
- 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.
- Match between documentation and real world terminology and concepts The documentation should use language and concepts that are familiar to users and avoid software-based terminology.
- Minimalist writing Topics should avoid information that is irrelevant. Every extra unit of information in a topic competes with the relevant information and diminishes the findability of relevant information.
- Consistency and standards Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform, software, and domain conventions.
- Integration with software Users should not have to leave their software workflow to access documentation. Provide search access to documentation from the product and context sensitive help where possible.
After you consolidate all the results of the evaluation for a specific user goal, you may learn that all the required tasks were completed and only a few minor changes to the documentation are necessary. For example, you may need to streamline the text in one or more topics or use terminology consistently.
However, you may also find that you or your peer evaluators could not complete the tasks because the topics that provide the information are disjointed and contain superfluous information that detracts from usability. Such issues probably require more intensive rework to determine how to best break up the information among topics. Furthermore, you may need to rethink how to link related topics in a more streamlined way. You may also choose to reexamine the topic titles to make them more goal-focused and less software-focused. Topic titles should summarize the benefit of reading a topic, much like newspaper headlines, and use user-familiar words.