How to Design Documentation with Users in Mind

We all have ideas about how something works; better yet—we all have ideas about how something should work. These ideas are based on our previous experiences. When products work the way we think they should work, we can successfully use them. When products do not work the way we think they should work, we get frustrated because we cannot successfully use them. So how can writers design documentation that addresses gaps between what the user knows about the product and what they need to learn about the product to understand how to use it successfully? How do we design documentation with the users in mind?

Let us start with a high-level view at the concept of shopping in a store. In most stores, items on sale are placed at the entrance. If you know what you are looking for, you go to that department (e.g., boys, girls, men, women, household appliances, music, or toys). You compare prices for similar products. You might ask for advice or help from a sales clerk. Eventually, you buy something or you leave the store with no purchases (see Figure 1). Or you may return an item and ask for either a full refund or an exchange (see Figure 2)—you have done this many times without problem.

Figure 1. User’s Mental Model of Shopping in a Store

User's Mental Model of Shopping in a Store

Figure 2. User’s Mental Model of Returning an Item

User's Mental Model of Returning an Item

When the consumer shops online, he still expects a comparable experience as in a traditional store; if his online expectations are not met, he will probably become confused and frustrated. There might be minor differences in the process. For example, instead of speaking with a sales clerk, the consumer will review customer comments. Instead of carrying the purchased item out of the store, the consumer has to provide shipment information for a purchase. This difference will hopefully not cause confusion, especially if the consumer has ever shopped from a catalog. However, we can’t assume the consumer has experience at catalog shopping.

The consumer applies the experience of shopping (Figure 1) to shopping online (Figure 3). Figure 3 shows what the consumer understands about the process of shopping online.

Figure 3. User’s Mental Model of Shopping Online

User's Mental Model of Shopping Online

Another example is understanding the functionality of a software program, such as Microsoft Word 2003. You know the process for creating a document: start a new file, edit text, change the layout, save the file, and print. Over time, you learn other functions, including shortcuts. When you upgrade to the next version, such as Word 2007, you recognize that aspects of the software have changed (e.g., the toolbar has changed to something called a ribbon and some menu options have changed to tabs). The improvements are based on extensive usability testing and card sorting, but you don’t understand the changes. You understand how the old version works. If you are a self-starter, you might search the Internet for tutorials on how to use Word 2007. Otherwise, you ask friends, family members, and coworkers for help. Eventually, you become proficient enough to accomplish everything that you used to do with Word 2003.

If someone asked you to explain the differences between Word 2003 and 2007, how would you do it? You could say: “The process for creating a document did not change, but the steps did.” Another way to explain it would be: “The mental model for creating a document is the same, but now you perform the steps using the ribbon.”

Cognitive psychology refers to the way we develop an understanding of how something works as a “mental model.” We develop mental models by observing what happens with a process and drawing conclusions about how the process works. Interestingly, a person can possess an incorrect mental model, such as not understanding the purpose of the ribbon in Word 2007, thereby frequently getting stuck when an old function cannot be initiated in the same way as it was in Word 2003. Technical communicators who understand the value of mental models will identify important concepts that help end users bridge the gap between a previous design and a new design for software programs.

Why We Should Care about our Users’ Mental Models

Mental models are a key concept in the development of instructions, documentation, tutorials, demos, and other forms of user assistance (Nielsen, 2010). If we don’t help users develop accurate mental models of how a software program is designed, then we leave users to their own devices for developing their own mental models. If their mental models are not correct, users may have problems using the program.

Another factor to consider is the differences between mental models for understanding high-level processes (e.g., creating and managing documents), as well as low-level processes (e.g., where are buttons typically located on the screen). The users may need our help to gain a clear understanding of the larger design for using the product as well as the detailed design elements.

Why Mental Models Are Important to Usability

Usability of any product is tied to the extent to which a user’s mental model matches and predicts the action of a system. Ideally, an interface design is consistent with people’s existing mental models about computers, the environment, and everyday objects. For instance, it makes sense to design a calendar program that has similar functionality and appearance to the notebook calendars with which everyone is familiar. As I have already mentioned, when the user’s mental model does not match the design of the design of the product, the user becomes frustrated and confused.

Practical Approaches to Understanding User’s Mental Models

There are several practical approaches to learning about the user’s mental models.

  • Sketching. In the very early stages of design, invite users to explain their understanding of every visual element of the product. If their explanation does not match the design or the design does not match their understanding, then you have identified possible problems that should be corrected in a redesign.
  • Card Sorting. Card sorting is a reliable and inexpensive method for finding patterns in how users would expect to find content or functionality. This method helps you identify an overall structure for your information, as well as suggestions for explaining (and developing) navigation, menus, and possible taxonomies.
  • Mind Mapping. Mind mapping is a visual representation of the tasks and decisions users are taking to perform a task in order to identify possible gaps between the user’s mental model and the developer’s mental model.
  • Thinking Aloud. When users verbalize what they think, believe, and predict while they use the system, you can piece together much of their mental model.

Methods to Help Users Develop Accurate Mental Models

When users are struggling to understand the process for using a program, it is wise to offer them different avenues toward finding the information they need. Manuals, online help, and instructional videos can appeal to people’s various learning styles, and offer multiple methods in which users can build accurate mental models of the program.

  • Marketing Brochures. A marketing brochure answers questions about the product in a logical sequence following the reader’s train of thought. The best way to start is by analyzing what users want to know, and then assess the order in which their questions will flow. A good way to organize your points is to write down the questions you think a potential reader might have and the answers your brochure might supply. This information would also appear on the product’s website under “About <Product Name>.”
  • User Guides. For user guides to be useful, they need to need to be written for various readers, ranging from those with little or no experience with the product to those with significant experience with the product (or similar products). The ideal user guide identifies the important high- and low-level processes that allow the reader to develop an accurate and useful understanding of the product. If you follow the Agile methodology, then writing to the user stories can be a helpful method for organizing topics in the user guide.
  • Quick Reference Cards. Few people want to read a book cover-to-cover when they only want to learn how to perform a few key tasks. A quick reference card gives an overview of the program and instructions on how to perform a few key tasks (e.g., create, edit, delete). The user can always refer to the manual to learn more detailed information. Quick reference cards are an ideal takeaway from any kind of training course.
  • Help. You are likely to find help in most programs and browser-based applications. For help to be useful, it should allow users to search topics for individual tasks, as well as for patterns between common tasks.
  • Instructional Videos. If users don’t like reading user guides, the next best thing is instructional videos, which help to reinforce concepts about how things work in a visual and memorable way. Instructional videos are typically available from vendor sites and YouTube.

If your document types provide content target to a range of users, so they can develop accurate mental models about the process of using the product as well as design patterns for individual tasks, then you will bridge the gap between what the software designers intended and what the users want to do.

A good way to enhance your knowledge about writing manuals, quick reference cards, help files, and instructional videos is to serve as a judge for your Chapter or an STC competition. What’s best about serving as a judge is the opportunity to discuss your findings and opinions with other STC members. The lessons learned are priceless.

Final Thoughts

Be careful not to allow your documentation and tutorials to be a solution to poor product design. Work with designers to simplify the product. Donald Norman writes in The Design of Everyday Things that design should achieve the following:

  • Make it easy for users to determine what actions are possible at any moment (and not possible due to constraints).
  • Make the invisible visible, including the conceptual model of the system, alternative actions, and the results of actions.
  • Make it easy for users to evaluate the current state of the system.
  • Follow natural mappings between intentions and the required actions, between actions and the resulting effect, and between the information that is visible and the interpretations of the system state.
  • Eliminate as many opportunities for error as possible.

Simply stated—the design should help the user to understand what is going on and help the user understand what to do. The design should be so well done that users do not need to rely on documentation to learn, but can make logical assumptions about how it works and build confidence and competency. This can be achieved by providing cautionary notes, notifications, and prompts.

Ideally, a user only needs to walk through a process once and commit it to memory to “keep the process simple.” In the real world, however, your usable documentation (reflecting the users’ mental models) will help the users to successfully use the product!


By David Dick, ©2014 Intercom, Volume 61 Issue 7, July/August.