How to Write Error Messages
Error Message Template – Download Now!
Here’s a suggested approach to writing error messages:
· Create a spreadsheet.
· Give each error a number so you can track them.
· Add columns for the error message and the root cause.
· Establish an error message quality-control team.
· Create simple to follow writing guidelines for the error messages.
· Find best practices. Share with the team.
· Include error and information messages in the design phase.
· Place the messages under source control.
· Review messages during development.
· Try to eliminate the need for messages, if possible.
· Carry out user acceptance tests.
· Review and revise messages periodically.
Error Messages Best Practices
Error Message Template – Download Now!
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.
Microsoft Error Message Guidelines
Error Message Template – Download Now!
When you write messages, 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
Example of IBM Software Error Messages
Error Message Template – Download Now!
The following is an example of how IBM writes error messages. Notice the words and phrasing as well as how the alert categories are explained.
Error Message
There is no value specified for the User ID.
Explanation
You must specify a value for the user ID.
Alert Category
Similar events are grouped in categories. The alert category is in the following format:
Severity – device component
Severity is one of the following severity levels:
· Critical: A key component in the server is no longer functioning.
· Warning: The event might progress to a critical level.
· System: The event is the result of a system error or a configuration change.
Sample Oracle Error Messages
Error Message Template – Download Now!
The following is an example of how Oracle writes error messages.
Notice the format of the error message:
· ORA-00058 – error number for tracking
· DB_BLOCK_SIZE must be string to mount this database (not string) – description of error message
· Cause: what caused the error to occur
· Potential reasons: note the use of the word potential in the following example.
· Action: what steps need to be taken
For example:
Cause: The value of the DB_BLOCK_SIZE initialization parameter used to start this database does not match the value used when that database was created.
Potential reasons for this mismatch are:
Mounting the wrong database
Using the wrong initialization parameter file
The value of the db_block_size parameter was changed
Action: For one of the above causes, either:
Mount the correct database
Use the correct initialization parameter file
Correct the value of the DB_BLOCK_SIZE parameter
Sample Microsoft Windows Error Messages
Error Message Template – Download Now!
The following is an example of error messages for Microsoft Windows XP:
When you try to install a program that uses the Windows Installer in Microsoft Windows XP, the program does not install, and you may receive an error message that is similar to one of the following error messages:
The Windows Installer service could not be accessed. Contact your support personnel to verify that the Windows Installer service is properly registered.
The Windows Installer service failed to start. Contact your support personnel.
Internal Error
This issue may occur when the Windows Installer files are missing or damaged.
To resolve this issue, use one or more of the following methods in the order that they are listed.
It then describes three different methods to resolve the issue.
Method 1: Reregister the Windows Installer
· Quit all Windows programs.
· Click Start, click Run, type msiexec /unregister in the Open box, and then click OK.
· Click Start, click Run, type msiexec /regserver in the Open box, and then click OK.
· Restart your computer.
Method 2: Remove the Windows Installer files
· Quit all Windows programs.
· Click Start, click Run, type msiexec /unregister in the Open box, and then click OK.
· In Windows Explorer, rename the following files in the %systemroot%System32 folder:
o Msi.dll
o Msihnd.dll
o Msiexec.exe
Note: If you cannot rename these files, try to rename the files at a command prompt. To start a command prompt, click Start, click Run, type cmd in the Open box, and then click OK.
· Restart Windows XP.
Method 3: Restart Windows XP in Safe Mode
· Restart Windows XP in Safe Mode, and then retry Method 1 and Method 2 in the order that they are listed.
Finally, it provides more information about how to restart Windows XP in Safe Mode, by suggesting you read the following article number to view the article in the Microsoft Knowledge Base:
316434 How to perform advanced clean-boot troubleshooting in Windows XP
Sample Google Chrome Errors Messages and Warnings
Error Message Template – Download Now!
The following is an example of error messages from Google Chrome. Note the tone, language, and phrasing.
You might see an error message when a download fails.
It will show up on the download bar at the bottom of your browser screen or in the download page that opens.
Note the use of the phrase ‘show up’ instead of display or appear. Likewise, the use of download in lowercase instead of uppercase.
If something you’re about to download could cause problems, Chrome also warns you.
Common warnings for harmful or unwanted programs
Certain downloads can cause viruses, leak your private data, change your browser and computer settings, or add unwanted extensions or toolbars to your browser.
Chrome warns you of potential issues:
Malicious download warning: You tried downloading malware.
Uncommon download warning: You tried downloading an unfamiliar and potentially dangerous piece of software. You should only download programs from sites you trust.
Unwanted software download warning: You tried downloading a deceptive piece of software. This program, disguised as a helpful download, may actually make unexpected changes to your computer.
Virus detected: Antivirus software detected a virus. Your downloaded file may have a virus and, as a result, the file you attempted to download was removed by the Windows Attachment Manager.
Summary
In the above example, note the direct ‘you’ phrasing, the relaxed tone, and the use of may and might to suggest the root cause.
This combination of tone, phrasing, and conciseness is encouraging to the reader as it avoids blame. You feel the writer of this Help page is on your side.