Q: What is an error message?
An error message describes a problem that stop a user or system from completing a task.
An error message must include enough information for the user to solve the problem.
What types of error messages are there?
In general, there are three types of error messages:
· Confirmations
· Warnings
· Notifications.
If a message has different audiences, create separate text for users, administrators, and developers.
Why do we use the word error in error messages?
Isn’t part of the problem the word error? It’s assumed the user made the error. If you think about it, the problem is often the software, for example, it wasn’t designed to accommodate unexpected behavior.
If we see it like this, the error is on the side of the developers. If that’s the case, you don’t want to blame the user just because they entered 05122020 instead of 12052020 when entering a date. I tend to use 0512 whereas maybe you use 1205. Good software anticipates this and, where necessary, provides the direction the user needs.
Error Message Template – Download Now!
Error Message Guidelines
Error messages should:
· Be helpful: explain how to fix the problem, avoid repeating it again, and saving any data you’ve entered, if possible
· Be specific: focus on one issue. Avoid general statements.
· Be precise: describe the issue in words I, the user, can understand.
· Educate: most users only read Help and tech docs when all else fails. Knowing this, write error messages that teach the user how to use the application. Examples help.
· Acknowledge something has gone wrong, then explain what to do next.
· Offer different levels of messages, some for beginners, others for advanced.
· Provide direction. Instead of saying, “not available,” provide a contact number, email or some way to find when they’re back in stock.
· Save the user’s work, if possible, so they don’t have to re-enter data.
· Use a positive tone: avoid blame.
· For information messages, use consistent grammar, terminology, and abbreviations.
· For dialog boxes, use consistent placement, colors, and size.
· Use words, phrases, and terms your audience will understand.
· Use Plain English – concise, accurate, no unnecessary words.
· Use ‘you’ centered phrasing.
Error Message Mistakes To Avoid
Try to avoid the following:
· Anthropomorphize. Don’t suggest the software has feelings or thoughts, for example, the PC died. Instead, say, it stopped responding or is not available.
· Blame. Maybe the user was at fault, for example, entered text into a field meant for numbers. However, instead of saying this was wrong, bad, or illegal, state that this field only takes numbers and encourage them to try again.
· Cryptic numbers. Error message 724ABC may mean something to the programmer but nothing to the user. In this case, refine the error messages to help the user, not the QA team debugging the application.
· Generic ‘catch-all’ messages. Determine the cause of the error and create an appropriate error message.
· Jargon. What does ‘syntax error’ mean?
· Jokes. Avoid. 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.
Error Message Template – Download Now!
How to Improve Error Messages
Ask yourself: how can I help the user solve their problem as painlessly as possibly?
Error Message Template – Download Now!
One problem with most error messages is that while they indicate that an error has occurred, they don’t mention what steps the user should take to a) avoid this happening again and b) resolve the current issue.
· Rewrite temporary error messages written during testing. Examples of these might refer to null pointer errors or issues with the class, objects, or interfaces in the code. None of this should be displayed to users when the product is finally released.
· Many error message leave the user in a type of limbo unsure what caused the issue and, for example, how to recover data they may have lost if the system crashed.
· If possible, create links to FAQ pages where users can learn more, download the necessary patches, or contact support.
· Get the technical writer to write and enhance the messages. If you’ve no tech writers on your team, assign them to the person with the best writing skills.
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.