Do’s and Don’ts when writing error messages:
Don’t
· Avoid the word “bad”. Use more descriptive terms to tell the user what is wrong. For example, avoid messages such as “Bad size”. Instead, tell the user what criteria to use when specifying a size.
· Avoid the word “please”. It can be interpreted to mean that a required action is optional.
· Avoid UPPERCASE text and exclamation points.
· Explain the solution to the problem. If it has more than one step, link to a Help page the explains the task in detail.
· Insert descriptors before a term to clarify the meaning of the sentence. For example, “Specify ID when Detect is set to No.” should be changed to “Specify the ID parameter if the Detect option is set to No.”
· Don’t suggest the software has feelings or thoughts, for example, the PC died. Instead, say, it stopped responding or is not available.
· Blame the user. Instead of saying this was wrong, bad, or illegal, state that this field only takes numbers and encourage them to try again.
· Use cryptic numbers. Error message 124589 may help QA but means nothing to the user. Re-write the error messages to help the user, not QA debugging the application.
· Generic ‘catch-all’ messages. Determine the cause of the error and create an appropriate error message.
· Don’t ever say it was a ‘syntax error’.
· Avoid Jokes. Not the time to be funny. People are frustrated.
· Negative phrasing, such as wrong, bad, invalid, and illegal.
· Using Red to indicate an error. Doesn’t help color-blind users or if printed out.
· Slang or abbreviations.
· Terms that may be offensive in certain cultures.
· The word error in the title bar.
Do
· State the problem in plain English. Explain what caused the problem. Use complete sentences.
· Use active voice if possible.
· Use passive voice to describe the error condition.
· Use the Cancel button to stop an operation and close the message box.
· Use the Close button to close a message box.
· Use the Details button to provide more information about the root cause.
· Use the Help button to provide more information about the solution.
· Use the present tense to describe the conditions that caused the problem.
· Write critical errors to an event log.
· Write separate error messages for each known issue.