![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
In this installment of the Quality busters series, I look at one aspect of application usability: error handling. Usability is a non-functional requirement that is often overlooked or ignored because of lack of funding, time, resources, understanding, and more.
What does MissingResourceException mean?
The SHEEP application team had finished deploying their new internationalized version of the application's rich client component. This new version allowed the user to select between English, Spanish, and German versions of the panel field labels.
During deployment, a spelling error in the name of the German resource bundle occurred in the configuration properties file. This was not detected until a user tried to select German and received the dialog window shown in Figure 1.
Figure 1. Example of a meaningless error message
The user called the help desk and asked, "What does MissingResourceException mean?" The help desk didn't know and forwarded the problem to the SHEEP application team. The lead developer immediately recognized the problem:"Oh, the German resource bundle is missing. Either the file is missing or the configuration is wrong. I'll look into it."
Generally, error messages delivered to a user fall into two broad categories -- user-caused and environment-caused.
- User-caused errors are notifications of incorrect program usage, such as invalid input data. Messages to the user should provide enough information to allow the user to fix the problem.
- Environment-caused errors are notifications of problems with computing resources, such as out-of-memory errors or problems that arise when the system is unable to access a server. Messages to the user should resolve the problem.
Regardless of the category, if the message does not provide sufficient information about the problem -- likely causes, runtime details, configuration information, and a suggested recovery process -- then the user wastes a lot of time, and consumes a lot of help center and programming resources working on problems that the user could have solved given enough information through messages. While the application team might save money by keeping user messages simplified during development, the team ends up spending far more money on application support to solve minor problems.
Different audience, different needs
Developers can cite many reasons why applications might have error messages that are meaningless from a user perspective:
- One cause might be developers ignoring the user's perspective. Developers create messages from their own perspective. Because they know the code in detail, they do not need redundant information in an error message. Location, exception name, and some field values are usually sufficient for a developer. But a user has none of this knowledge. As a result, these error messages are meaningless to a user.
- Another cause might be the lack of powerful user-oriented error-reporting facilities. Many packages and language APIs support logging messages, but few support user-oriented messages.
- Also, user-friendly error messages are difficult to develop. Generally, doing it well requires usability testing of the application and messages.
To produce a high-quality application, it's important for the application architect to remember that the user interface, which includes error messages, is for the users, not the developers.
In this section, I cover some tips on making your own error messages user friendly.
Useful error messages should contain at least the following information:
- Message ID. This is a unique message identifier associated with a specific
error. The message ID can function as an index into a procedures manual or a reference within a user's guide. If the message is translated into other languages, the identifier remains constant and thus can be consistently used to report errors. Most IBM software products have message IDs associated with errors; for instance, message AMQ4023 means that "The queue manager does not exist on this computer" in the WebSphere® MQ product.
- Timestamp. This is the date and time at which the error occurred. The help center or developers can use this information to correlate the error with information in log files.
- Message type and severity. Indicate whether the message is informational or reporting an error. You can divide errors into automatically recoverable errors, manually recoverable errors, and non-recoverable errors.
- Process and thread details. Show the identity of the effective user associated with the process, the identity of the process itself, and the identity of the active thread. These are details that will help developers troubleshoot the problem.
- A short message. Present the user with a short form of the error message. This is a compromise to balance the needs of advanced users and novice users.
- A detailed message. Permit the user to view detail information about the error if he chooses to do so.
- Program state and configuration. Instead of showing program stack information, which is not particularly useful to the user and belongs in the program log files anyway, show current program field values and applicable configuration information in the message. For example, don't say, "Queue manager not found"; say "Queue manager PHRED not found." Include information that is relevant to the user. If the error was caused by the user entering incorrect information, repeat the value that the user entered incorrectly. If the error was caused by a misconfigured component, display configuration information so that the user knows what the program was expecting.
- Likely causes. Offer an explanation of likely causes of the error. Write the description in user terminology, not programmer terminology.
- Corrective action or recovery. Provide instructions on how to recover from the problem. In some cases, these will instruct the user to contact the help center.
As you can see, even useful error messages will have a lot of information that can overwhelm a user. Therefore, you want to deliver the information in pieces, providing a way for the user to display just as much as he or she needs at any given moment. The initial dialog panel would show the basic information, as illustrated in Figure 2, and a subsequent dialog panel can show detailed information, as illustrated in Figure 3.
Figure 2. Sample basic error message dialog
Figure 3. Sample detail error message dialog
Remove as much of the user message text as possible from the program and move it to external objects, such as resource bundles, text files, or even database tables. Because the text is external to the program, it's possible to replace that text with local language translations, thus enabling the program for international use.
If possible, create and use a very clean message delivery API that the programmers can use in the application. The messages should show program state and configuration written to the message delivery API. One way to support this is to have the messages in the external message description objects support substitution parameters. The message delivery mechanism replaces these parameters with information passed from the program.
Listing 1 shows an example of how this might be done in the Java language.
Listing 1. Sample user error message API
//-- error occurs
userMessageDelivery.send( 'UDU0149',
MessageDelivery.ERROR,
MessageDelivery.RECOVERABLE,
new Object[] { parm1, parm2 } );
|
The message ID identifies the message. The message type indicates an ERROR. The message severity indicates that this error is recoverable. Finally, an object array of parameter values provides the values for the substitution parameters in the underlying message.
When building an interactive application, an architect starts by asking the following questions:
- Does the project plan include usability testing and analysis?
- What is the skill level of the user community? If the primary audience is programmers, as is the case with many open source products, then less information in error messages can be tolerated. However, with commercial products used by a wide range of users, plan to make more information available.
- Is the application targeting an international audience for which messages will be translated into local languages? This necessitates moving message text out of the program and into external objects, such as resource bundles in Java environments.
- Are there commercial products or open source code available to implement a more useful error reporting mechanism?
When users encounter a problem and are presented with poorly designed error messages, the results are user frustration, user rejection of the program, and increased support costs from user dependence on the help desk. Error reporting is an often-overlooked aspect of the total user experience. This article has proposed a minimum standard of contents and design for user error messages.
- Read the author's other articles in the Quality busters series on developerWorks.
- The author derived many of the ideas for the proposed message contents from the message facility of the OS/400 (and OS/i5) operating system that is used on the IBM eServer iSeries (and i5) family of computers. IBM Application System/400 Technology is a book that came with the announcement of the AS/400 series, the successor of the System/38 and predecessor of the iSeries and i5 series. The book includes articles about the user interface and application design using the message file, message description, and message queue objects.
- Get the details on the usability analysis underlying the radically different command language and user screen design of the System/38 operating system and application screens from "The Design Rationale of the System/38 User Interface," J.H. Botterill IBM Systems Journal, 1982).
- Explore a pioneering work on GUI application design drawn from experiences learned especially using Apple Computer systems in Tog on Interface by Bruce Tognazzini (Addison-Wesley, 1992).
- Check out the first book anyone preparing for usability analysis of an application should read, Usability Engineering by Jakob Nielsen (Morgan Kaufmann, 1994).
- Discover how usability decisions impact users in Don't Make Me Think: A Common Sense Approach To Web Usabilityby Steve Krug (New Riders, 2000).
- Find guidelines on how to avoid common error message problems in GUI Bloopers: Don'ts and Dos for Software Developers and Web Designers by Jeff Johnson (Morgan Kaufmann, 2000).
- Visit these valuable resources on developerWorks:
- The Web Architecture zone specializes in articles covering various Web-based solutions.
- Browse for books on these and other technical topics.
Michael Russell has a bachelor's degree in physics and a master's degree in computer science. He was a logistics engineer, a technical services manager, and a certified IT architect at IBM for nearly 14 years. He is currently a Web application architect for a resort company in Orlando. He has experience in Windows, UNIX, and OS/400 environments. He uses Web technology for entertainment through his own company, Vicki Fox Productions (http://www.VickiFox.com).
Table of contents
Local resources
Tags
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
