5 Ways to Write Better Error Messages

When you write error messages for software development projects, follow these guidelines:

  • Avoid vague wording. Give specific names and locations of the objects involved.
  • Avoid “please.” It can be interpreted to mean that a required action is optional.
  • Do not refer to implementation details that are invisible to the user. For example, do not refer to the names of functions or objects in the program.
  • Avoid phrasing that will seem silly to the user, such as “unexpected error.”
  • Avoid using placeholder variables in the middle of a message. They are very hard to localize.

Correct

The name of the object file conflicts with that of another program in the project. File name: %s

Works did not find a match for this term.

Incorrect

You have named the object file with the name of another program in the project. File name: %s

The term you typed does not appear in this Works file.

Source: Manual of Style for Technical Publications

Error Messages Template

Use this Error Message Guide template (14 pages MS Word) to show users how to resolve error messages that may appear in your application. This template also comes in the Technical Writing Template Pack (233 pages MS Word). Scroll down for more details and screenshots.

Download Now for only $4.99!

Download Template