Common Desktop Environment: Style Guide and Certification Checklist

Error Messages

Use error messages to present crucial messages to the user when user intervention is necessary for the successful completion of an operation. Error messages are intended to bring a problem to the user's attention and to help the user resolve the problem.

Guidelines for Error Messages

Use a Motif error dialog box to present application error messages. Figure 8-1shows a typical error dialog box. Keep in mind the basic three-part structure for error messages. Whenever possible, each message should tell the user:

Figure 8-1 An error dialog box.

Graphic

The text describes the error, why it happened, and offers to retry the operation. A Help button in the lower right will bring up appropriate online documentation.

Recommend 

gd: 

Error messages displayed by your application indicate the possible cause of the error and indicate the possible actions the user can take in response. 

Keep the information in the ErrorDialog clear and concise. The idea is to alert users to the problem, have them quickly understand the problem, and learn how to recover from it. A large amount of text makes it more difficult for the user to focus on the critical information. 

Recommend 

gc: 

Messages displayed by your application do not assume that the user has any expert knowledge about computer systems in general, or the UNIX system in particular. 

It is appropriate to assume that the user has knowledge about basic terms used within the desktop, such as files or programs. Such knowledge can be assumed to have been learned by the user through tutorials, online help and user documentation. However, terminology that is typically understood only by an expert or frequent computer user should be avoided unless the application is specifically targeted at computer professionals. Likewise, messages returned to your application by the underlying operating system should not be passed through to the user, but instead, should be "translated" into language that can be understood by the novice user.

Try to make the error message specific to the immediate situation and as helpful as possible. For example, if the user has entered an invalid name, the error message should not simply state that an invalid name was entered. Instead, tell the user which character was invalid. If the rules for valid names are simple, describe them in the error message; otherwise, describe the rules in the online help and give the user access through the Help button.

In many cases, the only user response to an error dialog box will be to click the OK button to dismiss the dialog box. However, often it may be possible to offer to resolve the problem for the user. If you have buttons for user actions, be sure to also include a Cancel button.

Optional 

ge: 

Your application uses audio feedback, in addition to any messages displayed, to signal error conditions and events. 

Optional 

gh: 

Urgent conditions that require immediate attention by the user, no matter which application or desktop service the user is currently accessing, are brought to the user's attention using audiovisual notification. The alarm is signaled in the current workspace regardless of the workspace in which the application resides. 

Some applications, such as network monitors or stock watch programs, may need to grab the user's immediate attention to some event. Both visual and audio alarms should be used to signal the user. The user should be able to acknowledge the alarm and cause it to cease. 

Keep in mind that the user may be running several applications at once, and may be focused on another application while your application is running in the background and encounters an error. The application name should appear in the title bar, to help the user identify the source of the error message.

Once users have read an error message, they may need to access other parts of their system to resolve the problem. Whenever reasonable, posting an error dialog box should not block further interaction with your application and, if at all possible, it should not block other applications.

Optional 

gq: 

Your application writes error messages to the Common Desktop Environment error log when it is not appropriate to display these to the user in a message dialog box, but when the message may nevertheless be useful in diagnosing problems. 

You might also write error messages that are displayed to the user in the error log if it would be valuable to the user or an administrator to refer to these messages at some later time. Messages written to the error log should provide additional information about the error and should state the context in which the error occurred.

Access to Online Help

Recommended 

gj: 

Your application provides a Help button in all message dialog boxes, except those that contain self-explanatory messages. 

Applications should be designed with both the expert and novice user in mind. The novice user must be able to access additional information clarifying the message, the circumstances under which it might have been displayed, and what the user should do in response to the message. 

The brief description of the problem in the ErrorDialog should be sufficient for the experienced user, but may not contain enough information to enable less experienced users to resolve the problem. Rather than confusing the dialog with additional text, use the Help button to take the user directly to the online documentation for a more detailed description of the error, its causes, and methods for resolving the issue. Users who still need additional help can browse the general online help facilities from there. A few notices may not need Help buttons because the text of the message will cover the condition sufficiently.

For more information on how to access online help directly from the error dialog box see the Help System Author's and Programmer's Guide.

Helpful Hints

Optional 

gh: 

Urgent conditions that require immediate attention by the user, no matter which application or desktop service the user is currently accessing, are brought to the user's attention using audiovisual notification. The alarm is signaled in the current workspace regardless of the workspace in which the application resides. 

Applications should not send messages to command entry windows or to the UNIX console (that is, applications should not write to the default UNIX files stdout or stderr). Applications are often launched by double-clicking icons in the File Manager, Front Panel, or Application Manager, which means users will not see messages that are written to stdout or stderr. Even if the application is launched from a terminal window, the user may subsequently close the terminal window, and messages appearing there will often not be seen. Worse, if the user does not have a console window running (the console window is difficult to launch in Common Desktop Environment), messages intended for the console may blast across the screen and make everything look ugly.