Software usability and documentation

Usually, good documentation decreases support costs. However, do not expect documentation to correct users' problems that are caused by bad software design. Instead, to decrease the requirement for documentation, have a user-centred strategy for software design.

The benefits of software usability

People think about usability when they buy software. Customers want software that does not waste their time or irritate them. Research shows that if customers are offered 2 products with the same functions at the same cost, they choose the product that is easier to use. Companies such as Microsoft, Compaq, and Lotus include usability as part of their advertising campaigns. Most product reviews include usability.

Software that is easy to use can be cost-effective, with benefits not only to the users, but also to the software developers, the support team, and the documentation team. IBM shows that for each £1 that is spent on usability, the return on investment is between £10 and £100.

In 2004, McAfee released new software. Because McAfee designed the user interface carefully, McAfee received 90% fewer calls to their service desk than they had expected. [Editor's note: Reference not available.]

Good software usability decreases the need for documentation

Documentation is necessary only when the software cannot supply the information that a user needs. The table shows the effect on documentation of Jakob Nielsen's best practice heuristics for software design (

Good software usability decreases the need for documentation
Heuristic Explanation Effect on documentation
Visibility of system status The system tells users what occurs. Information that is on a screen usually does not need to be repeated in documentation.
Match between system and the real world The system uses words and concepts that the users know, instead of system-oriented terms. Terms that users know do not need an explanation. For example, if the interface shows, "Enter an integer", then possibly the documentation must explain the term 'integer'.
User control and freedom Users can easily find 'emergency exits' if they choose system functions by mistake, and they can undo and redo operations. If a user can undo accidental operations, the documentation does not need to explain how to recover from an unintended system state.
Consistency and standards Each word, phrase, and image is used consistently, with only one meaning. Consistency helps to prevent confusion. The documentation does not need to explain apparently different terms.
Error prevention A careful software design that prevents a problem is better than an error message. If a problem is prevented, documentation is not necessary.
Recognition rather than recall Objects, actions, and options are visible. The user does not have to remember information. Instructions are visible or easily retrievable. If information is on a screen, repeating the information in documentation is usually not necessary.
Flexibility and efficiency of use Accelerators are available to experts, but are not seen by novices. Users can customize frequent actions. Wizards can guide new users through a process. Usually, wizards do not need additional documentation.
Aesthetic and minimalist software design Dialog boxes do not contain information that is not applicable or that is not usually needed. Additional information competes with the applicable information and decreases its relative visibility. Possibly, this requirement leads to additional documentation for information that is not usually needed. Because most people do not need the information, but some people do need the information, put the information in online help.
Help users to recognise, diagnose, and recover from errors Error messages are the in users' language. Error messages show the problem and suggest a solution. Unclear error messages require additional documentation. First, the error message must be explained. Then the solution to the problem must be given.
Help and documentation Ideally, help is easy to search, focused on user tasks, and not too large. If the software conforms to standards and operates as users expect, the requirement for explanations is decreased.

Chris Rourke from User Vision Ltd ( helped to write this article. Contact Chris for advice on how to improve the usability of software.

See also

Usability, testing, and documentation

Extreme Programming is a user-centred strategy for software design (

RSS feed