Error Messages: Best Practices for Supportable Product Development

By Samartha Vashishtha
Senior Content and Community Lead, Adobe Systems

While functionality deservedly remains the primary focus in the development of any software product, it’s also important to ensure that the product is easily supportable. Error messages – being the first line of support for a product – contribute significantly to product quality and the customer experience that it delivers. Poor error messages that are “plugged in” as an afterthought towards the end of the product lifecycle lead to frustrated customers, avoidable support costs, and loss of corporate goodwill.

Structural foundations of a good error message

A good error message is direct, short, and communicates just the right amount of information. When you write or review error messages, attempt to cover answers to the following questions:

  • Is the message an error, warning, question, or a piece of information for the user? The error message could begin with labels like Error: or Warning:
  • What exactly is the error? For example, Error: Could not write to the disk …
  • If the message is an error or a warning, the message should clearly capture what went Error: Could not write to the disk because it is full.
  • What is the solution/workaround? If no workaround is available, request users to contact the Customer Support Organization. Error: Could not write to the disk because it is full. Delete some files and try again.

Additionally, every error message should have a unique alphanumeric error code that customers can quote when they call customer service for support. These error codes also come in handy when customers are searching for troubleshooting information on the Web. In fact, content strategists often metatag troubleshooting documentation and technical notes with error codes as an SEO measure.

Wherever possible, error codes should be duly displayed in dialog boxes, especially for enterprise products for which customers have priority access to customer support. These messages could be unobtrusively displayed in a collapsible panel or a smaller font variation. For example:

error message png

Wording error messages

In an ideal world, error messages need to be a shared responsibility of product engineering, technical communication, content strategy, and User Experience Design (XD) teams. However, owing to timeline constraints and the fact that error messages are often treated just as a checklist activity, developers often end up writing error messages without much review support. Wordsmithing assistance is often sought late in the cycle and only for identified “problematic” error messages.

While writing error messages, developers/testing engineers can consider the following writing guidelines:

  • Use short sentences; 15 words at the maximum. Limit the error message to a maximum of 2-3 sentences.
  • Keep the sentences friendly, actionable, and conversational. Avoid a patronizing or reprimanding tone. Transfer the blame on the software rather than the user.
  • Avoid negative words like abort, catastrophic failure, execute, human error, etc. A typical example of a negative error message is the infamous DOS “Bad command or file name” message.
  • Avoid using programming jargon. However, it’s OK to use the necessary terms if the error message is intended for a predominantly developer audience.
  • Avoid over-communication. Unless absolutely necessary, do not include technical details about the error. Users are most interested in resolving the error as soon as possible and carrying on with their work.

blue screen

Over-communicated jargon: The Blue Screen of Death (BSoD)

  • Get the error message peer/buddy-reviewed. Involve your content strategy counterpart in the review process, whenever required.

Looking ahead…

The following suggested process improvements would facilitate the creation of useful error messages:

  • For easier review and localization, separate error message content from functionality code. Instead of hard-coding error messages, display error messages by reference.
  • Error messages should be part of the “Done” definition for agile sprints and significant milestones. If that is not feasible, error messages should at least be part of sprint backlog items.
  • Error message review should be part of buddy code reviews as well as quality reviews.
  • Review support from the content team should be enlisted earlier in the cycle, especially for priority components that significantly impact user experience

While tracking error messages as part of the overall program plan might seem like an initial overhead, benefits realized in terms of customer loyalty, reduced support call volumes, and fewer “reactive” fixes far outweigh the efforts.

/by