Crafting an effective exception message

  • Article

Microsoft Dynamics AX typically displays four classes of messages:

  • Confirmation messages

A confirmation message is displayed to verify whether the user wants to complete an action. For example:

Do you want to save the changes to the customer registration? [Save, Do not save, Cancel]

  • Error messages

An error message is displayed when an exceptional condition is met and the application cannot resolve the condition. For example:

You are not authorized to delete user group <name>. Contact the security administrator to resolve this exception.

  • Notification messages

A notification message is displayed to communicate the occurrence of an event that a system or user asynchronously sends for receipt. For example:

A workflow work item has been assigned to you.

  • Warning messages

A warning message is displayed to communicate a condition that may occur in the future. For example:

If you modify the address on this form, the address registration will need to be updated manually.

Do you want to continue? [Yes, No]

In this blog entry I examine one type of message—the error message. I focus on the structural components of this type of message, and I offer considerations and patterns for writing this type of message.

But first, I propose a class name change to the class of messages that we name error message. While an error message seems to be correctly named when an exceptional condition occurs with respect to data validation, this type of message seems misnamed as an error message when, from the perspective of the user interface, documentation requirements are not met.

A more accurate name that I propose for this concept and class of messages is exception message. You will note that I use the term exception message throughout this entry to refer to the class of message that is named error message in Microsoft Dynamics AX 2012.

The purpose of an exception message

Exception messages are displayed to the user when an exceptional condition is met and the application cannot resolve the condition. Ideally no exception message should be displayed. However, when exception messages are displayed, they should be effective.

When I review an exception message, I review it to determine the effectiveness of it with respect to audience and to ensure consistency in the exception messages that are delivered across the application. In my evaluation, I consider the following questions:

  • To whom is the exception message written?
  • What aspect does the exception message take: an aspect inside of the application code or an aspect of the real world—that is—the experience of the user?
  • Is the exception message:
    • Accurate
    • Informative
    • Actionable
    • Grammatically correct
    • Is the exception message written in a naturally conversational voice?
    • Does the exception message contain:
      • An exception statement
      • A cause statement
      • A resolution statement

In the sections that follow, I examine these questions in more depth, and I offer guidance for writing exception messages.

Audience

Anyone who uses the Microsoft Dynamics AX application—partners, developers, customers, customer support professionals—is a candidate for seeing an exception message.

These audiences use the application from two different aspects: an internal aspect, that is, the application code, and an external aspect, that is, the real interaction with the user interface. And each aspect uses a unique vocabulary to communicate. The internal aspect uses a programming language vocabulary, and the external aspect uses a vocabulary of terms and verbs that exist in the real-world domain.

While neither vocabulary on its own is inaccurate, when we consider the diversity of the Microsoft Dynamics AX audience, we must assess how we choose between the vocabularies, voice, and tone in exception messages and how we ensure consistency in exception messages across the application.

We do know that mixing the programming language and domain vocabularies creates a unique small-group vocabulary that alienates more people than it helps because in this small-group vocabulary, we are forced to bridge the communication of complex conditions and concepts by creating neologisms, such as post financial inventory, and nonsensical phrases, such as edit customer.

Given that an exception message is a condition that occurs as a result of an exception to the application code or as a result of a documentation requirement that is not met, they are often first authored by contributors who have deep expertise of the internal workings of the code. While the exception messages that are written may be technically correct, they generally tend to use the vocabulary of the application code, and that vocabulary does not transfer well to those users who do not have deep expertise in the internal workings of the application. For those audiences whose primary roles include working with the user interface instead of application code, exception messages that favor the vocabulary of the application code do not use a vocabulary that is consistent with the domain nor are they easily understandable to those users who do not have deep expertise in programming languages.

The question I consider in the rest of this blog entry is: How do we write exception messages that address both aspects while maintaining the data necessary to enable the recipient of the exception message to address the exceptional condition that has occurred?

Writing audience-neutral exception messages

If we have to choose one vocabulary for communicating with the various audiences that use the Microsoft Dynamics AX application, it seems we should choose an established, neutral vocabulary. Given that audiences that use the Microsoft Dynamics AX application comprise partners, developers, customers, and customer support professionals who work in various industries, domains, roles, and locales, we should favor the established vocabulary and term choices that exist in the real-world as opposed to that of only one specialized area, such as the application code. And we should focus the exception message on the needs of the person, not on the needs of the application.

If we take a people-focused approach, then audience-neutral exception messages should consider characteristics such as:

  • Being user-centric.
  • Being actionable.
  • Being relevant to real-world industries, domains, roles, and locales.
  • Using neutral domain term and verb choices.
  • Being naturally conversational.
  • Being clear, concise, and consistent.
  • Occurring infrequently.
  • Not anthropomorphizing the application.

The components of well-constructed exception messages

While an exception message should consider the characteristics offered in the preceding section, it should document the following:

  1. The exception – Document that a processing exception occurred.
  2. The cause – Document why the processing exception occurred.
  3. The resolution – Document a resolution to the processing exception.

Examples of well-constructed exception messages include:

  • Project contract number <identification number> does not reference a valid funding source. Select a valid funding source for the project contract.
  • The entity type attribute name already exists. Enter a unique entity attribute name.
  • The relationship of the person named as the emergency contact to the person named as the employee must be provided. Select a relationship.
  • The location that you entered was not found in the reference list of countries and regions. Add the location to the reference list, or select one of the reference country/regions.

The components of poorly constructed exception messages

Exception messages that do not consider characteristics such as those that I offer in the Writing audience-neutral exception messages section tend to be less effective because they often:

  • Frustrate the user.
  • Describe the processing exception without offering a resolution, describe the processing exception and cause only, or offer only a resolution.
  • Offer actions that fail to solve the processing exception.
  • Intimidate the user by using a vocabulary that requires deep expertise in application code or use a made-up vocabulary, including terms and verbs, that is understandable to only a small group of people.
  • Blame the user for the exceptional condition.
  • Use a voice and tone that trivialize the exceptional conditions.
  • Contain information that is inaccurate, imprecise, incomplete, or redundant.

Examples of poorly constructed exception messages include:

  • The validity of the kanban rule must be within the validity of the related production flow version.

This exception message describes the processing exception from the aspect of the application code and mixes the vocabulary of the application code with the vocabulary of the domain. This exception message does not align terms and verbs accurately with respect to the domain. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: The effective date for a kanban rule cannot be earlier than the effective date of the production flow, and the expiration date of the kanban rule cannot be later than the expiration date of the production flow. Enter an effective date later than or on the production flow effective date, and/or enter an expiration date earlier than or on the production flow expiration date.

  • The value <value> in field 'Country/region' is not found in relating table 'Country/region'.

This exception message describes the processing exception from the aspect of the application code. It does not use terms precisely or accurately with respect to the domain, is not audience neutral, nor does it use a naturally conversational voice. It does not offer a resolution to the processing exception.

Corrected exception message: The location that you entered was not found in the reference list of countries and regions. Add the location to the reference list, or select one of the reference country/regions.

  • The record may not be deleted. Transitions exist in table ‘Category hierarchy roles’.

This exception message describes the processing exception from the aspect of the application code. It does not use verbs precisely or accurately. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: Category hierarchies cannot be deleted until dependent category hierarchy roles are deleted. Delete dependent category hierarchy roles and try again.

  • %(wildcard for datefield) must be later than or equal to the termination date.

This exception message describes the processing exception from the aspect of the application code. It does not use terms precisely or accurately, is not audience neutral, nor does it use a naturally conversational voice. It does not contain an exception statement or a resolution to the processing exception.

Corrected exception message: The position retirement date <date> must be set to a date that is later than or on the employee termination date. Select a later position retirement date.

  • A record with RecId <number> does not exist

This exception message describes the processing exception from the aspect of the application code. It uses the vocabulary of the application code, is not audience neutral, and the sentence is not punctuated. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: The purchase requisition number PR-0357911 was not found. Contact the system administrator to resolve this exception.

  • Insufficient rights to execute Menu Item Posting.

This exception message describes the processing exception from the aspect of the application code. It does not use terms precisely or accurately, is not audience neutral, nor does it follow sentence-style capitalization guidelines or use a naturally conversational voice. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: You are not authorized to open the Posting form. Contact the security administrator to resolve this problem.

Structural components and writing considerations for exception messages

Addressing how we communicate processing exceptions, their causes, and their resolutions effectively requires us to think about what it is that we communicate in exception messages, how we communicate it, and to whom we communicate it.

In this section, I propose guidelines for writing exception messages. I offer guidelines for identifying the components and characteristics of exception messages, and I offer patterns for structuring and writing exception messages.

A few key considerations for guidelines for structuring and writing exception messages might include:

Structural components

Each exception message should include the following structural components:

  • Each component—the processing exception, the cause, the resolution—should be limited to one sentence each.
    • The exception statement is required.
    • The cause statement is optional.
    • The resolution statement is required.
  • The exception statement and the cause statement can be combined if necessary to enable the natural flow of the exception message.

Writing considerations

Exception messages should:

  • Be user-centered. The exception message should focus on the user’s action and not describe what occurred in the application code.
  • Be set in the present tense, use active voice, and use a naturally conversationally tone.
  • Use precise and accurate domain-specific terms and verbs.
  • Use specific names of resources, events, agents, locations, and the values of the objects that participate in the activity from which the exception message occurred.
  • Be context aware and processing context aware. The exception message should present an action that the user can take to resolve the processing exception. If the user is not authorized to resolve the processing exception, the exception message should direct the user to a person who can resolve the processing exception, for example, the security administrator.
  • Be relevant to the processing exception that occurred. The exception message should not be vague or attribute human behavior to a condition that occurred in the application code.
  • Use complete, grammatically correct sentences that follow the subject-verb-object order.
    • The first sentence of an exception message should start with an article, a pronoun, or a noun.
  • Use sentence-style capitalization.
  • Use punctuation as prescribed in standard grammar books.

Combining the structural components and writing considerations: Patterns

The structural components of an exception message determine format of the pattern. We know we need at least two sentences. The writing considerations offer guidance for the content that appears in the exception message.

Combining the structural components and writing considerations for documenting exception messages informs patterns that can be applied to types of exception messages. For example, a few patterns that might appear in guidelines for writing exception messages might include:

  • Pattern: Exception statement. Resolution statement.

Writing convention: <Article, Pronoun, or Noun> <description of processing exception>. <Article, Pronoun, or Noun> <description of resolution>.

    • Examples:
      • The position retirement date <date> must be set to a date that is later than or on the employee termination date. Select a later position retirement date.
      • You are not authorized to add a new active employee registration. Contact the security administrator to resolve this exception.
  • Pattern: Exception statement and cause statement. Resolution statement.

Writing convention: <Article, Pronoun, or Noun> <description of processing exception> because <article, pronoun, or noun> <description of cause>. <Article or Pronoun> <description of resolution>.

    • Example:
      • The form cannot be closed because the distributed amount <monetary amount> does not equal the source document amount <monetary amount>. Select the source document amount and modify the accounting distribution amounts so that the distributed amount equals the source document amount.

  • Pattern: Exception statement. Cause statement. Resolution statement.

Writing convention: <Article, Pronoun, or Noun> <description of processing exception>. <Article, Pronoun, or Noun> <description of cause>. <Article or Pronoun> <description of resolution>.

    • Example:
      • The entered or selected product is classified as a <product classification>. A subcontracting service must be classified as a service. Enter or select a product that is classified as a service.

  • Pattern: Delete data entity.

Writing convention: ‘<Table label1>’ cannot be deleted until dependent ‘+ tolower( <table label2>) +’ are deleted. Delete dependent ‘+ tolower(<table label2>) + ‘ and try again.

    • Example:
      • Category hierarchies cannot be deleted until dependent category hierarchy roles are deleted. Delete dependent category hierarchy roles and try again.

  • Pattern: Internal data consistency processing exception.

Writing convention: The <table.singularlabel> number <identification number> was not found. Contact the system administrator to resolve this exception.

    • Example:
      • The promissory note number ABC-13579 was not found. Contact the system administrator to resolve this exception.

For more information

For information about content on the user interface, see my earlier blog entry, Content is the user interface.

For information about writing in a naturally conversational voice, see my earlier blog entry, The state of equilibrium: Balancing the voice of the application and the voice of the customer.