Heuristic Inspections for Documentation 10 Recommended Documentation Heuristics
by Vesa Purho, Nokia
We all are familiar with Jakob Nielsen's heuristics for evaluating the usability of interfaces. When I was conducting a study on documentation usability, I started wondering if there existed a similar set of heuristics for evaluating the usability of documentation. The natural place to pose such a question was the STC Usability SIG mailing list. The response was that there was no heuristics set available although someone had tried to open the discussion in the mailing list some time ago. An answer, which led to the list of heuristics presented below, was something along the line "Well, now that you asked, why don't you put the heuristics together" and so I did.
I combined all kinds of general ideas about what is good documentation and made a list of heuristics that I sent for comments to the usability mailing list. After making some modifications based on the comments, I came up with the following ten statements:
1. Match between documentation and the real world
The documentation should speak the users' language, with words, phrases, and concepts familiar to the user, rather than system-oriented terms. Follow real-world conventions, making information appear in a natural and logical order.
2. Match between documentation and the product
The forms, screens, manuals, and online helps system should match so that the same terminology is used in all of them. This may contradict with "Match between the documentation and real world" if the interface uses strange terminology.
3. Purposeful documentation
If the documentation set contains several documents, the purpose of each type of document should be clear, as well as the intended use. The media of the documentation must be purposeful so that users get what they need. For example, people working on a rooftop installing some hardware would not necessarily be delighted with nice multimedia CD-ROMs but prefer a laminated quick reference card.
4. Support for different users
The documentation should support users with different levels of knowledge on the domain as well as those assigned different tasks in the domain. Any unnecessary information for a specific user must be hidden from other users or be easily overlooked. Quick reference information for expert users should be available.
5. Effective information design
Information must be presented in a way that it is easily found and understood by the users. Short lines and paragraphs are easier to read. Graphics, tables, and lists are easy to scan and read, and appropriately used to support the information need the user has. Unnecessary graphics only slow the reading and the download time of web-based documentation. Write instructions in imperative form and address the user directly using active sentences.
6. Support for various methods for searching Information
Documentation should support people with different strategies for finding information: some search through the table of contents, some use the index, some browse, and some use searches (in electronic documentation). The index should contain users' own terminology as well as system terms, terms from international standards, and those used by competitors. The layout of documentation should support browsing so that beginnings of new chapters and important warnings and notes are easily picked up.
7. Task orientation
Instructional documentation should be structured around the users' job tasks, that is, tasks that are independent of the tools used. The job tasks remain the same although the tools may change. For example, the job task "baking bread" remains the same although the baker may do it all by hand or using latest state-of-the-art tools. This reduces the need to restructure the documentation when the product is changed. The tasks should be approximately at the same level of granularity throughout the documentation
The documentation should contain a troubleshooting section giving users guidance for common problem situations and how to analyze rare situations. All documentation related to errors must be easily accessible.
9. Consistency and standards
Users should not have to wonder whether different words, situations, or actions mean the same thing. If the product has several documents, they should be consistent in their structure and the information in different documents should be designed so that no unnecessary overlapping exists. Follow platform conventions when creating the help system. Be sure that the terminology is consistent throughout the documentation suite.
10. Help on using documentation
If the documentation set is large, provide instructions on intended use, and how it is going to be updated (if separate updates are delivered).
Of course, heuristic statements are only generalizations and never replace careful planning and user-centered design processes. However, they can be used as a checklist on matters that need to be considered when designing documentation. One way to use them is to derive more specific checklists from the heuristics and add company and product specific statements to be used in planning and evaluation. If you have any comments on the heuristics, I would be glad if you can post them to the STC Usability SIG mailing list for discussion.