Home > Sample chapters

The Microsoft Manual of Style: The User Interface

Messages

When explaining a message, include the situation in which the message occurs, the message text, and what the user should do to continue. Do not use special formatting (such as monospace or bold) or title capitalization to set off messages from surrounding text unless specified in your product style guide. Instead, set the text off on a separate line or enclose it in quotation marks, as appropriate.

Programs use four types of messages:

  • Errors

  • Warnings

  • Confirmations

  • Notifications

Errors

An error message alerts a user about a problem that has already occurred. Error messages can be presented by using modal dialog boxes, in-place messages, notifications, or balloons.

httpatomoreillycomsourcemspimages1831381.jpg

When referring to errors, follow these guidelines:

  • In content for a general audience, refer to errors as messages, not alerts, error messages, message boxes, or prompts.

  • For acceptable uses of alert, see alert.

  • Error message is all right to use in content for a technical audience to describe messages that indicate an error condition. It is also all right if you must follow the user interface.

  • Refer to errors by their main instruction. Use the exact text, including its capitalization. If the main instruction is long or detailed, summarize it.

Microsoft style

If you receive a “There is no CD disc in the drive” message, insert a new CD disc in the drive and try again.

If you receive Windows Update error 80072ee7 while checking for updates, you might need to change or remove static IP addresses for the Windows Update service.

International considerations

For machine-translated content, do not embed error message text that forms a completed sentence inside the sentence that makes a statement about the error message. Instead, structure the sentence so that the error message text is set off on a separate line or rewrite the sentence so that the error message text becomes a grammatical part of the sentence in which it is embedded.

For example, consider the following sentence:

  • If you receive a “There is no CD disc” in the drive message, insert a new CD disc in the drive and try again.

To make this sentence better for machine translation, restructure this sentence as follows:

  • If you receive the following message, insert a new CD disc in the drive and try again: “There is no CD disc in the drive.”

  • or

  • If you receive a message that states that there is no CD in the drive, insert a new CD disc in the drive and try again.

Set error messages that are not completed sentences off on a separate line if you can. If you cannot, enclose the error-message text in quotation marks to mark the text as one unit.

For example, the following sentence may cause mistranslation:

  • If you receive Windows Update error 80072ee7 while checking for updates, you might need to change or remove static IP addresses for the Windows Update service.

For better machine translation, restructure this sentence as follows:

  • If you receive the following Windows Update error while checking for updates, you might need to change or remove static IP addresses for the Windows Update service: 80072ee7

    or

    If you receive “Windows Update error 80072ee7” while checking for updates, you might need to change or remove static IP addresses for the Windows Update service.

Warnings

A warning message is a modal dialog box, in-place message, notification, or balloon that alerts the user of a condition that might cause a problem in the future.

httpatomoreillycomsourcemspimages1831383.jpg

When referring to warnings, follow these guidelines:

  • In content for a general audience, refer to warnings as messages, not alerts, warning messages, message boxes, or prompts.

  • Warning message is all right to use in content for a technical audience to describe messages that indicate an error condition. It is also all right to use if you must follow the user interface. However, do not use warning without the word message.

  • Refer to the warning message by its main instruction, which may be a question. Use the exact text, including its capitalization. If the text is long or detailed, summarize it.

Microsoft style

If you receive the “This file has been modified outside of the source editor. Do you want to reload it?” message, click Yes.

Confirmations

A confirmation is a modal dialog box that asks if the user wants to proceed with an action.

httpatomoreillycomsourcemspimages1831385.jpg

When referring to confirmations, follow these guidelines:

  • Refer to confirmations as messages, not alerts, warning messages, message boxes, or prompts.

  • Refer to the confirmation by its main instruction, which may be a question. Use the exact text, including its capitalization. If the text is long or detailed, summarize it.

Notifications

A notification informs a user of events that are unrelated to the current user activity, by briefly displaying a balloon from an icon in the notification area. The notification could result from a user action or significant system event, or could offer potentially useful information from Windows or an application.

httpatomoreillycomsourcemspimages1831387.jpg

When referring to notifications, follow these guidelines:

  • Refer to a notification as a notification, not as a message, a balloon, or an alert.

  • Refer to a notification by its main instruction. Use the exact text, including its capitalization. If the main instruction is long or detailed, summarize it.

  • Refer to the notification area as the notification area, not the system tray.

Microsoft style

The Offline Files icon in the notification area intermittently displays the “You are working offline. You are no longer connected to Server” notification.

For information about how to write messages, see the Messages section of the Windows User Experience Interaction Guidelines on MSDN.