Does anyone use a style guide for error messages?

Question

I've noticed that error messages tend to be written in a handful of common styles. Either in full-form, casual-friendly sentences, or in shortened passive ones that don't always form a full sentence. The latter of the two seems to be the more common - though maybe not as common as the haphazard mixing of styles that I see in a lot of applications.

Does anyone include error messages in their style guide? I'm more curious about opinions on the consistent grammatical construction of these things than about the content of them, which has already been discussed.

Answer 1

Both the iPhone Human Interface Guidelines and the Apple Human Interface Guidelines contain sections on alerts.

Also, the Windows User Experience Interaction Guidelines have information for a few different types of dialogs, including error messages.

(iPhone)

As you compose the required alert title:

• Keep the title short enough to display on a single line, if possible. A long alert title is difficult for people to read quickly, and it might get truncated or force the alert message to scroll.
• Avoid single-word titles that don’t provide any useful information, such as “Error” or “Warning.”
• When possible, use a sentence fragment. A short, informative statement is often easier to understand than a complete sentence.
• Don’t hesitate to be negative. People understand that most alerts tell them about problems or warn them about dangerous situations. It’s better to be negative and direct than it is to be positive but oblique.
• Avoid using “you,” “your,” “me,” and “my” as much as possible. Sometimes, text that identifies people directly can be ambiguous and can even be interpreted as an insult.
• Use title-style capitalization and no ending punctuation when:
• The title is a sentence fragment
• The title consists of a single sentence that is not a question
• Use sentence-style capitalization and an ending question mark if the title consists of a single sentence that is a question. In general, consider using a question for an alert title if it allows you to avoid adding a message.
• Use sentence-style capitalization and appropriate ending punctuation for each sentence if the title consists of two or more sentences. A two-sentence alert title should seldom be necessary, although you might consider it if it allows you to avoid adding a message.

If you provide an optional alert message:

• Create a short, complete sentence that uses sentence-style capitalization and appropriate ending punctuation.
• Avoid creating a message that is too long. If possible, keep the message short enough to display on one or two lines. If the message is too long it will scroll, which is not a good user experience.

Avoid lengthening your alert text with descriptions of which button to tap, such as “Tap View to see the information.” Ideally, the combination of unambiguous alert text and logical button labels gives people enough information to understand the situation and their choices. However, if you must provide detailed guidance, follow these guidelines:

• Be sure to use the word “tap” (not “touch” or “click” or “choose”) to describe the selection action.
• Don’t enclose a button title in quotes, but do preserve its capitalization.

-

(Mac)

Alert message text. This text, in emphasized (bold) system font, provides a short, simple summary of the error or condition that summoned the alert. This should be a complete sentence; often it is presented as a question. See “Writing Good Alert Messages” for more information.

Informative text. This text appears in the small system font and provides a fuller description of the situation, its consequences, and ways to get out of it. For example, a warning that an action cannot be undone is an appropriate use of informative text.

A good alert message states clearly what caused the alert to appear and what the user can do about it. Express everything in the user’s vocabulary.

To make the alert really useful, provide a suggestion about what the user can do about the current situation. Even if the alert serves as a notification to the user and no further action is required, provide as much information as needed to describe the situation.

-

(Microsoft)

The characteristics of good error messages

In contrast to the previous bad examples, good error messages have:

• A problem. States that a problem occurred.
• A cause. Explains why the problem occurred.
• A solution. Provides a solution so that users can fix the problem.

Additionally, good error messages are presented in a way that is:

• Relevant. The message presents a problem that users care about.
• Actionable. Users should either perform an action or change their behavior as the result of the message.
• User-centered. The message describes the problem in terms of target user actions or goals, not in terms of what the code is unhappy with.
• Brief. The message is as short as possible, but no shorter.
• Clear. The message uses plain language so that the target users can easily understand problem and solution.
• Specific. The message describes the problem using specific language, giving specific names, locations, and values of the objects involved.
• Courteous. Users shouldn't be blamed or made to feel stupid.
• Rare. Displayed infrequently. Frequently displayed error messages are a sign of bad design.