Architecture & DesignThree Questions to Answer When Reporting an Error

Three Questions to Answer When Reporting an Error

Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Most error messages suck. They reveal little about the problem at hand and even less about how to pursue a remedy. Whether the device is a computer, cell phone, or automobile, most times, when an error message appears, it’s as if you are getting a telephone call from your doctor telling you that you are sick, and then he hangs up. You’re left wondering if you have a cold requiring some cough medicine or a brain tumor requiring immediate surgery. Instead of being a helpful experience, most error messages produce anxiety, confusion, and annoyance.

Let’s take a look at a recent error message that sent me into a tizzy. Figure 1 shows an icon that suddenly appeared on the dashboard on my car. (In the world of automotives, icons are the lingua franca for reporting information to the driver.)

Error1
Figure 1: A mysterious icon suddenly appears on the dashboard of my car. Is something wrong? If so, what’s wrong? What caused the problem? How do I fix it?

When the icon first appeared, I had no idea what it was about. Was something wrong? Was my car going to stop dead in the middle of the highway? Or, was the icon trying tell me that to attend to something at a later time? All I could do was wonder. It was only when I arrived at my destination twenty minutes later and did a search of the Internet did I get the information that described the situation. My tire pressure was low. Good thing I didn’t have to figure all this out while I was driving.

Mysterious error messages abound in the world of software development, too. Take a look at the example shown in Figure 2. The graphic shows the dialogs that appear when Visual Studio crashes.

Error2

Figure 2: The error messages that are emitted when Visual Studio crashes tell me little about what is going on. All I can do is hope that the IDE will start working again sometime soon.

First, you get a dialog telling you that the program has stopped working, which confirms the bad news, but offers little support. Then, after a bit of time goes by, time in which I am sitting at my desk wondering what’s going on, a second dialog appears asking me if I want to send more information about the problem. What is the problem? What’s the information? Where is it going to be sent? Is Visual Studio ever going to come back? Is my work day over? All I know is I’ve been given two dialogs that have told me nothing other than Visual Studio has stopped working and that information is going to being gathered. It’s as if a plane has crashed and the FAA representative says nothing more than, “we’re looking into it.” It’s not the most reassuring response in the world.

Reducing the Cost of Badly Written Error Messages

And then there is the cost. Years ago, I worked for one of the biggest computer manufacturers on the planet. The company had a floor full of service techs who spent their day on the phones helping customers in distress. Want to know a significant cause of distress? Cryptic error messages. At $27 a call, the cost that the company estimated was incurred every time a tech picked up the phone, we’re talking millions of dollars a year taken off the bottom line.

At the time, I worked in the User Experience group of that computer company. Our mission: Get the call rate down. One of the first things we went for were error messages emitted by the software we made. The Usability Ph.D in charge of the group had a simple rule for error messages: All error messages are to answer three questions in a clear and easy to understand manner. These questions are:

  1. What is the error?
  2. What is the probable cause of the error?
  3. What is the probable remedy?

Thus, using the rule laid down by the Ph.D, this less than stellar error message as shown in Figure 3 below…

Error3
Figure 3: Just telling a user that an error has occurred is not enough

…gets transformed into the one shown in Figure 4:

Error4
Figure 4: A good error message puts the user at ease while conveying the error, the reason, and a probable remedy

This simple rule worked. The call rate did go down. Users were less baffled and, more importantly, less anxious in error situations. Most customers followed the cordial instructions on the screen. They tended not to pick up the phone in an impulsive panic and spend $27 of the company’s money.

The lesson, The 3 Questions to Answer in an Error Message, has served me well over the years. So, allow me to take a few minutes to share the details of the lesson learned with you in a real life programming situation.

Improving the Evil HTTP 500 Error

Most of my work is server side, focusing on publishing APIs. However, just because I don’t work in the world of eye candy anymore, it does not mean I have abandoned the rule I learned back in that Usability Lab. In fact, when it comes to writing code for other developers to use, providing a good error message becomes critical. Let’s take a look at one of the most common error messages that programmers have to deal with in the world of coding for the Internet, the notorious HTTP 500 Error.

A 500 Error, Internal Server Error, is generated when something goes wrong internally in on the web server. 500 Errors get generated for a variety of reasons, reasons which most times are kept hidden from the person or code getting the error. It’s not unusual to get a 500 Error like the one shown in Figure 5.

Error5
Figure 5: An HTTP 500 Error has occurred. A value is out of range. What is the value? What is the range?

The server is reporting that something is wrong, something about a value being out of range. But, what is the value? What is the acceptable range? Imagine being the programmer having to work this error. Think of the amount of time he or she will need to spend just to figure out what is going on. Had the developer generating the error been a bit more thoughtful, a lot of brain strain could have been avoided.

Figure 6 is a revised error message describing the out of range problem. Notice that the 3 Questions are answered.

Error6
Figure 6: A good error message will report in a clear and understandable manner: What is the error? What is the cause? What is the remedy?

Figure 6 lets the user know the error is an out of range error. And, as an added bonus, the error message reports back the value that caused the error. The reason for the error is described clearly. Also, the message provides a suggested remedy. A developer getting this message is not going to have to take time to step through lines of code just to get an understanding of what’s going on. The error message is telling him or her exactly what is wrong and offers a way to fix the problem. The developer might groan at the error, but at least s/he won’t be angry. Again, the error message answers the 3 Questions: What is the error? What is the cause? What is the remedy?

An out of range error is but one of the multitude of exceptions that programmers handle. Still, this single example above serves as a good template for error reporting overall. State the error. State the cause. State the remedy. Remember, if you are writing code for other developers, help them out. Give them error messages that inform and save time, not cause confusion and waste time.

Things Are Getting Better

The practice of writing error messages that improve the user experience has come a long way since the days when we kept computers connected to the Internet using phone lines and modems. The rule I learned way back when, although not universal, is taking hold. Take a look at the screenshot of a Firefox browser error in Figure 7. Notice that the 3 Questions are answered as is required of a good error message. (1) on the upper left describes the error at hand. (2) on the right explains the probable cause and (3) describes suggested remedies. Clearly, the UI developers over at Mozilla understand the need to keep the user’s comfort level high, even in the face of distress.

Error7
Figure 7: The Firefox error message describes (1) the error, (2) the probable cause of the error, and (3) suggested remedies

Putting It All Together

Error messages can be the bane of your work or a useful helper to those using your application. As I’ve mentioned many times in this article, the trick to creating an effective error message is to answer the 3 Questions within your message:

  1. What is the error?
  2. What was the probable cause of the error?
  3. What is the probable remedy?

Whether it’s for a developer or a typical end user, publishing error messages that answer the 3 Questions will go a long way toward making your application a pleasant, productive experience. Answering the 3 Questions is an easy pattern to follow. You’ll be happy when you do. Because, as we have learned out here on the terrain, providing pleasant, productive computing experiences for all is what it’s all about.

Bob Reselman is a software developer and technology writer living deep in the heart of West Los Angeles, California. Bob looks forward to hearing from readers about their Tales of Error Message Horror. You can write Bob with your tale of horror at reselbob@gmail.com.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories