Non-Fatal Errors: Creating Usable, Effective Error Messages
By Emily Wilska
It's often easy to identify what kinds of error messages don't help users, but it can be tricky to avoid them, and even more of a challenge to create the opposite: error messages that give users a clear indication of the problem, offer information to help them fix it, and provide tips on how to avoid the same situation in the future. This paper details the steps involved in creating understandable, helpful error messages, and suggests ways of communicating the value of good error messages to managers and executives.
Error messages often suffer from being an afterthought in project planning and implementation. Scrambling to get something–anything!–in the product to deal with problems users might encounter, we fall back on standard error messages, overly general or technical text, and confusing functionality. Even if error messages are part of the original project plan, they tend to be much less a priority than other on-screen text or help.
Because error messages don't benefit from benign neglect, it's up to technical communicators to actively work on improving the quality of error messages in their products. The steps below can help.
The article is presented through the following sections:
The bad, the obtuse, and the utterly perplexing
Each time I connect to my ISP, I get a pop-up informing me that there's been a "Runtime Error!" [original emphasis] in something called the "Visual C++ Runtime Library." The message goes on to note, "This application has requested Runtime to terminate it in an unusual way. Please contact the application's support team for more information." Every time I see the error, I do the only thing I can do to make it go away: click the OK button.
I have no idea what the error is trying to tell me, why I have to see it every single time I connect, or what clicking OK actually does, other than dismissing the panel. Am I causing irreparable harm to my computer? Should I really be calling customer support? Isn't there anything I can do to make this error go away for good?
This is a great example of a bad error message. It does almost everything wrong:
How could this error message be improved? For starters, it could be prevented.
Prevention can be the cure
The old axiom about an ounce of prevention clearly applies to software and Web site errors--that is, it's far more effective to stop problems before they happen than it is to allow them to happen and expect users to recover. With even a modest amount of advance planning and some basic usability testing, you can determine where your users (or your software) might run into trouble, and recommend changes to the product to prevent that trouble.
For example, the error message above seems to stem from a persistent but relatively benign problem with the ISP's software. If someone at the company had taken the time and effort to identify and fix that problem, I (and my fellow ISP users) would be spared the frustration of having to see an error message each time I connect.
Stopping error messages before they happen involves creating programs and Web sites that not only do what they're supposed to do, but also foresee where users (or backend software) might get stuck; and then implementing methods of easily and effectively getting those users unstuck. Anticipating and designing around potential errors can help prevent your users from encountering error conditions in the first place.
It's not possible to predict all problems users might encounter; even if you meticulously plan and test your product, technical bugs and other unexpected glitches can introduce additional error cases. However, there are relatively easy and straightforward practices you can use to prevent the errors you can anticipate.
For example, if your Web site requires users to create a password, and that password must be at least five characters long, say so right on the page, close to the text box where the user will type the password. Not all users will read all (or any) requirements you list, but those who do will not have to deal with seeing an error message after trying to create a four-character password.
While not all technical communicators are able to provide feedback and recommendations on aspects of a project such as software functionality, page flows, and layouts, those who are have a valuable opportunity to stop potential errors before they happen.
Making unavoidable error messages less painful
Even after you've eliminated error messages through prevention, chances are you'll still have a sizable list of errors. Grace A. Stoeckle notes, "Not every element of every Web site [or program] design can cater to every user. [A] site that seems to be quite usable to one user may produce occasional erroneous actions for another user." (1)
It's nearly impossible to prevent error conditions altogether, whether your user base is large and varied or small and homogeneous. At some point, you will need to rely on error messages to help your users succeed at their tasks. As Stoeckle says, "An effective error message should quickly save the user after the primary design and content of an application fail to guide the user down the path of success." (2)
Though there are as many error messages as there are problems that need to be fixed, all error messages should provide some basic information:
Just as important as providing this information in the first place is providing it in a way that will be clear and helpful to your users. For each error message you create, take into account format, content, and tone.
The format you use for error messages depends on three main factors:
Technical limitations A full discussion of various Web and software technologies and their limitations is beyond the scope of this paper. Eliding specific details, however, one of the most important guidelines to keep in mind is that the strengths and restrictions of the technology you're working with should be among the first things you take into account when planning error messages. For example, planning for and writing full-page errors before verifying that your Web site supports them can result in hours or days of work wasted; worse, depending on where you are in your project cycle, it can force you to quickly redo your error messages in a format that doesn't meet your needs. Take the time to understand what error message formats your Web site or program supports before making a final decision.
Amount of information presented If the message you need to communicate to users is brief–"Sorry, our Web site is currently undergoing maintenance. Please try again later," for example–it might be more effective as a pop-up than as a page or on-screen text, depending on the design and layout of the site. Short chunks of text can easily be lost on a page with other content; on otherwise empty pages, they might look odd and out of place. Messages that require more detailed information, such as those that list several possible causes of the problem and several different solutions, work better as full pages. Trying to fit a large amount of text in a pop-up will result in an error that may seem unreadable.
User input required Finally, you should choose an error message format based on how much and what type of input, if any, you require from a user to correct a problem. Errors that inform users of problems they can't fix, or that require only basic action from the user, are well-suited to pop-ups. For example, if your message simply needs to tell a user that a portion of your Web site is currently unavailable due to maintenance–a situation in which you're asking the user to do nothing more than try accessing the page later–a pop-up might be the best choice.
If the problem at hand requires the user to do something more substantial–to retype information, for example, or to answer a question–consider using either on-screen text or a full page error message. On-screen text can be particularly useful in forms, which tend to have multiple text- or other data-entry fields. Should a user make a mistake in the address field, for example, you can quickly direct his attention to the problem by providing an on-screen error message directly above or next to the field. On-screen errors are often the best choice in cases in which a user must fix multiple problems on one page before submitting the page or completing the task at hand.
For shorter forms or wizard-like procedures, where the user provides information step-by-step, full-page errors can be helpful. ("Page" here refers to the standard UI element your program uses, not necessarily to a browser page; if the program uses a wizard, for example, a full-page error would be one that is the same size as the rest of the wizard dialogue boxes.) Consider a mail sign-up sequence in which you ask the user to, among other things, choose the e-mail address she'd like to create. If the address she types is already taken, show her a full-page error that repeats the unavailable address ("The e-mail address email@example.com is already taken") and allows her to try creating a different one.
In addition to considering the most effective format for your error messages, consider what content each message needs. Remember, the main goal of error messages is to tell users what's wrong and then get them back to their task as quickly as possible. As such, give serious thought to how much detail about each problem your users will need. Some might benefit from seeing specific information on a problem like a server timeout, but weigh the needs of those users against the needs of people who just want to know two things: What's the problem? What can I do to fix it?
If you're writing for developers or other highly technical audiences, you can safely use complex technical language and references; in fact, your error messages might be ineffective without such terminology. For example, if I were an engineer looking to troubleshoot my ISP's runtime error, I'd likely want the detailed technical information the error message provides. However, as an end user, that information doesn't mean anything to me, and doesn't help me solve the problem. If you're writing for an audience of anyone other than technophiles or subject matter experts, keep your error messages as clear, focused, and free of industry jargon as possible.
One exception to this rule is error cases severe or complex enough to require assistance from customer support. While error messages in these situations should still be relatively free of technical terms and references, you may want to consider adding an error number somewhere in the message; customer support agents can use this number to identify the problem the user is experiencing.
In spite of how much error-prevention planning you do or how user-friendly your product is, your users will make mistakes–quite possibly needless, preventable, seemingly silly mistakes. It can be tempting to chastise or blame users who make such errors, but doing so is almost guaranteed to make the problem worse. Laying blame on the user won't get her to pay closer attention to your Web site's friendly design or your program's easy-to-use format; it will frustrate her, shame her, and possibly cause her to abandon the task she was trying to do.
You can easily diffuse blame in your error messages by using the imperative (stating what the user needs to do), what we might call the fault-free declarative (stating the problem that needs to be fixed or the requirements for completing a task), or a combination of the two. For example, an error message informing the user that the password she typed is too short might say "Type a password that is at least five characters long" (imperative), "Your password must be at least five characters long" (fault-free declarative), or "Your password must be at least five characters long. Type a new password in the box below" (a combination). Any of these would be a marked improvement over "You typed a password that is too short."
Providing the information the user needs–what's the problem, and how can I fix it?–in a straightforward, friendly manner is one of the most important things you can do to make your error messages effective and usable.
Getting buy-in for error message creation
Many project teams don't think much about error messages until usability test participants–or, worse yet, paying customers–start having trouble with the product. At that point, it can be too late to create and implement truly effective error messages.
Even if you as a writer or editor include error messages in your user assistance plan, getting buy-in from other members of your project team, from management, or from executives can be a challenge. How can you prove to others that it's worth their time and resources to include error messages in a project plan?
For starters, consider the cost of ignoring error messages altogether, or of shipping a product with sub par error messages. An earlier version of my former company's Internet service included an error message that read, in its entirety, "This page is too big to be shown completely." What did it mean? Why were users seeing it? How could they get rid of it?
That's exactly what our customers wanted to know, and why they called or emailed our customer service agents asking about this error message hundreds of times over a two-year period. Those customer support costs–for one nine-word error message–came to just under $50,000.
The cost wasn't strictly monetary, either. While we don't have a record of anyone canceling a service subscription because of this error message, there can be little doubt that the message helped contribute to customer frustration and dissatisfaction. The relatively small amount of effort and development time required to improve this message would have paid off in a better user experience and a more usable product.
There's no set formula for getting buy-in from your colleagues and management; each company and team operates with different rules and different dynamics. However, emphasizing the importance of good error messages in terms of reduced support costs, a user-friendly product, and more satisfied customers can be effective on several levels. Members of your project team probably share your desire to ship a high-quality product. Marketing and customer retention specialists likely want to do what they can to ensure content and loyal users. Management and executives, who have to worry about the company's bottom line, are often willing to consider proposals that help keep costs down.
Planning for, creating, and implementing effective error messages will mean more work for your project team, and may also involve additional expenses in terms of writing, development, and usability testing. However, there is an excellent chance that this extra investment will return significant dividends in terms of a better product, more satisfied customers, and lower support costs.
As Scott Berkun notes, "When a user sees your error message, the Web site or product has let them down."(3) The challenge technical communicators face is to keep that disappointment as brief as possible and, as Berkun writes, "to shorten the distance between the user's goal and the completion of that goal." (4)
With planning; a careful consideration of format, content, and tone; and the desire to improve both your product and your customers' view of it, you can create error messages that are effective, useful, and relatively painless.
(1) Stoeckle, Grace A., "Error Messages: More Important to Your Web Site Than You Think," MarketingProfs.com, December 2, 2003, www.marketingprofs.com/3/stoeckle1.asp
Emily Wilska worked as a technical writer for Microsoft before leaving to start her own professional organizing company, The Organized Life. She currently takes on technical writing projects on a freelance basis. In her spare time, she copyedits articles for Boxes and Arrows and volunteers with the San Francisco STC chapter.