Writing error messages

Posted September 3rd, 2008 by Anne Gentle

Goals

Effective error messages reflect the “personality” of the application (helpful vs. hard-to-use, direct vs. indirect, confident vs. submissive) and keep the customer calm and positively focused. Error messages must use customer-domain terms, not “programmer-speak,” and must tell customers how to correct the problem, thus educating them at the same time.

If error messages are written effectively, customers are happier and Tech Support receives fewer calls. In addition, the customers become more educated in the use of the application. The more proficient a customer feels in using a software application, the more evangelizing they will do within their organization and within their industry about the application.

The goal of iMIS error messages is to project the following personality traits:

Is firm and authoritative
Doesn’t brag; doesn’t grovel
Uses neutral language
Tells the truth
Is consistent
Speaks to the user’s point of view about their tasks, not system tasks/concerns
When a serious problem occurs, is polite in giving a full explanation of how to remedy the condition

Language

The error messages should be user-empowering. They should be worded positively, imply that the user is in control, and
provide insight into how to use the application properly.

Speak in the user’s language.

Write the message to relate the user’s task at hand, instead of giving a technical, programming-oriented
explanation.

Wrong: Failed to create object.

Right:
Select Create to set up your list.

Wrong: Create link cancelled.

Right:
You have stopped linking.

Wrong: Printer not found! [Abort, Retry,
Ignore]

Right: The selected printer is not available. Do you want to select a different printer? [Yes, No]

Use a professional voice.

User tests have shown that groveling error messages make the corrective action seem more like “work”
to the user.

Write the message in as neutral and business-like of a voice as possible. Do not use “please” in the
message, unless our product has caused an unrecoverable error or serious problem. Use the second person (you/your) when referring to
the user.

Wrong: Please enter a numeric value.

Right:
Enter a numeric value.

Right: Customer Management is shutting down due to an internal error. Please contact your system
administrator.

Don’t blame the user.

Use a neutral, business-like voice to state the problem and a clear solution. Do not use exclamation points; they are
interpreted as shouting.

Wrong: You have input the wrong information.

Right: The account number must be 8 digits in length.

Wrong: Enter a correct date value.

Right:
Enter a date in the format MM/DD/YYYY.

Wrong: You have already uploaded a file with that name. Would you like to overwrite it?

Right: A file with that name has already been uploaded. Do you want to overwrite the file?

Wrong: No contacts selected!

Right:
Select a contact.

Grammar Guidelines

Follow the ASI Style Guidelines for iMIS 10 (posted in iMIS Toolkit community).

Use present tense.

Where possible, use the present tense. The user is doing the task in real-time.

Wrong: Windows could not find the file.

Right: Windows cannot find the file.

Consider sentence fragments for brevity.

Sentence fragments are okay, if the information is complete.

Right: Edits
canceled.

Use affirmative voice.

Write in the affirmative, not the negative.

Wrong: Do not use CTRL+ALT+DEL to restart your computer.

Right: To restart your computer, select Restart.

Use correct input action verbiage.

Use “press” to describe a keyboard action. Use “select” to describe a
window selection. Use “enter” to describe a typing action.

Right: Press Ctrl+L to use the Lookup feature.

Right: Select Save.

Right: Enter a numeric value.

Capitalize field and button names.

Right: Select Save.

Right: Enter a Distribution Code.

Content Guidelines

Provide all needed information.

Whenever possible, include the following elements in your error messages:

TELL the user the problem
IDENTIFY why the problem occurred
INSTRUCT the user how to resolve the problem or inform them of the necessary action to take

Including these elements in your error messages allows the user to recover from a mistake and educates them for
future operation. Write the recovery steps in the order that they must be performed.

Wrong: If you open another record, your edits will be lost.

Right: You have unsaved changes in your open record; save or cancel them before opening another record.

Wrong: You’ll need to restart your computer after you reinstall the program.

Right: Reinstall the program and then restart your computer.

Right: To update users for the new security model, log in to iMIS as an administrator, and select User>
Password Maintenance> Update All Logins.

Don’t use “Are you sure…?”.

Users ignore “are you sure” warnings and get irritated. Instead, describe the consequences of the action
and then ask them if they want to perform the action.

Wrong: Are you sure you want to delete the record?

Right: If you delete this record, all associated records such as activities and subscriptions will also be deleted. Do
you want to delete the record?

Example Error Messages

Here are some examples of correct error messages. It may save you time to cut and paste these into your code whenever
possible. Please feel free to add additional examples for the list.

Authorization/Security

You are not authorized to do x.

You are not authorized to delete <type> records.
You are not authorized to add new customers.

You are authorized to do x only.

You are authorized to edit the following Member Types only: <types>.

Credit Card Authorization Process

Authorization process in progress. If the process takes longer than 3 minutes, it will be canceled. {Where space is limited: Authorization in progress. If longer than 3 minutes, it will be canceled.}
The authorization process timed out. Please contact your system administrator.
The credit card does not pass the validation check. Do you want to override the validation check?
Authorization failed. Enter a valid Credit Card Number or a different payment type.
This transaction will be marked for deferred authorization and capture. Please notify your system administrator.
A credit card authorization was completed for this transaction before the payment amount was changed to zero. Delete the transaction and re-enter it with correct information.
Invalid path for Credit Card Authorization Preference file. Verify the path in A/R Cash module setup.
The system cannot locate the service: [fControlName]. Credit card authorizations will be held for the rest of this session and sent for processing together. Please contact your system administrator.
Delete this transaction to void the charge. If additional funds need to be refunded, insert a new credit transaction.
This transaction has been authorized. Delete the transaction to void the charge.
Your credit card information has not been validated. Error message from credit card gateway: Referral. Enter the data again or contact your credit card company.
We were unable to complete your transaction. The credit card information was submitted, but no orders were committed. The Webmaster has been notified of the error.
We were unable to complete your transaction. The credit card transaction was voided and orders were not committed. The Webmaster has been notified of the error.

Data Entry

Basic Entry

Enter a unique Major Key.
Enter a numeric value.
Enter a value for the Purpose.
Enter a value for the Note.
Enter the search criteria.

Data Additions, Deletions, and Edits

Edits canceled.
Restart iMIS for edits to take effect.
The activity record was added.
Returns cannot be edited. Delete the return and re-enter it with correct information. {Where space is limited: Returns cannot be edited. Delete the return and re-enter it.}
If you do x, y will happen. Do you want to do x? (Y/N)

If you delete this activity attachment, it will be permanently deleted. Do you want to permanently delete this activity attachment? (Y/N)
If you delete this activity record, it will be permanently deleted. Do you want to permanently delete this activity record? (Y/N)
If you delete this community, all the archived documents, discussion forums, and news items for this community will be deleted. Do you want to delete the community? (Y/N)
If you delete this forum, all the discussion posts for this forum will be deleted. Do you want to delete the forum? (Y/N)
If you delete this record, all associated records such as activities and subscriptions will be deleted. Do you want to delete the record? (Y/N)
If you delete a Single Gift or an Installment down-payment, there will be no audit trail. Do you want to delete this transaction? (Y/N)
If you change the Customer Type, the matching plans available for the current ID will disassociate. Do you want to change the Customer Type? (Y/N) (Note: In some windows, the field is still called Member Type, so the error message for those windows should say “Member Type.”)
If you edit the List As information on the Overview tab, it will not update the List As information in the Customer Portfolio Donor Data tab. Do you want to edit the List As information?
If you send a reminder, this entry becomes permanent. Do you want to send a reminder? (Y/N)
If you close this window, your changes will not be saved. Do you want to close this window? (Y/N)
If you change the organization ID when a matching gift is selected, the matching gift information will be deleted. Do you want to change the organization ID and delete the existing matching gift information? (Y/N)

Format/Limits

Don’t tell the user they entered data that doesn’t meet the limits or format. Instead, tell them what the
limits/format are.

Note: Because this is data entry, use numbers instead of text for all numeric amounts.

Enter x in the format y.

Enter a date in the format MM/DD/YYYY.
Enter an Expiration Date in the format MM/YY.
Enter an e-mail address in the format ‘name@organization.com’.
The <field> must be x.

The account number must be 8 digits in length.
The ID must be 10 characters or less in length.
The Gift Amount must be $21,000,000 or less.
The receipt Quantity must be greater than zero.
X must not exceed y.

This field must not exceed <field length>. The data has been truncated.
The transfer quantity must not exceed the quantity available in warehouse <location>. Re-enter the transfer quantity.
Select only one x.

Select only one address for Mail Preferred.
Select only one address for Bill Preferred.

Invalid Entry

If applicable, tell the user which field contains
the invalid data, but always supply the information they need to make
a valid choice.

Invalid x. Do y.

Invalid product. Select a product from the list.
Invalid Tax Code. Select a Tax Code from the list.
The matching amount for this plan is zero. Select another Matching Plan.
The Label Preference '<label>' is already assigned. Select another Label Preference.
Incomplete address information. Update the Ship To information.
This Interest Code is already assigned. Select another Interest Code.
The Label Preference '<label>' is already assigned. Select another Label Preference.
This Notify ID is already assigned. Select another Notify ID.
Invalid Quantity. Re-enter the Quantity.

x not allowed. Do y.

or x allowed only when y.

Commas, spaces, and quotation marks are not allowed in passwords. Enter a new password.

Out-of-sequence dates are not allowed for installments. Enter new dates.
In-kind payments are not allowed for <type> gifts. Enter a new payment type.
Edits are allowed only on the date of authorization.
Deletions are allowed only on the date of authorization.

x required. Do y.

Passwords must contain at least one number and one letter. Enter a new password.
x must match y. (Optional: Do z.)

The <field> must match the <field> in the <title> window/tab.
The Gift Amount must not exceed the open credit amount.
The total installment amounts must match the Gift Amount in the Overview tab.
The split gifts total must match the Total Amount in the Overview tab.
This matching request originates from transaction <number> and cannot be associated with matching gift transaction <number>. Select another request.
The Amount From must be smaller than the Amount To. Re-enter the amounts.
The From Date must be earlier than the To Date. Re-enter the dates.

No x were found for y: <value>.

No transactions were found for date: <date>.
No transactions were found for transaction: <number>.
No transactions were found for ID: <number>.
No records were found. Enter different search criteria.

Missing Information

Required information is missing: <field label, field label>.

Required information is missing: First Name, Last Name.
Required information is missing: Check #, Credit Card, In-kind, or Asset.
Required information is missing: Credit Card Number, Expiration Date.
Required information is missing: In-kind Description.
Required information is missing: Installment Date.
Required information is missing: ID.
Required information is missing: Fund.
Required information is missing: Distribution.
Required information is missing: Gift Amount.
Required information is missing: Authorization Code.
Required information is missing: Amount from, Amount to.
Required information is missing: Match %.
Required information is missing: Login ID and Password.

Select or Enter x (optional: choices for x).

Select a registrant class.
Select a record.
Select a product to print.
Select a campaign to print.
Select a file type: htm, html, or txt.
Enter the payment type: Check #, Credit Card, In-kind, or Asset. {Need to rewrite this one when we change the field label.}

Notification

Transaction <number> is not a fund raising transaction.
No transactions were found for transaction <number> or it is not a fund raising transaction.
The <institute prompt> Name does not match the Sort information.
The data you entered does not match our records. Please contact <orgname>.
A reminder has already been sent.
A reminder has not been sent.
This event is full. Please contact the <institute prompt> for availability.
This custom tag is unknown. Add the file [filename] to your [directoryname] directory. No transactions or orders were committed.
This CFX tag is not registered. Register [tagname] in ColdFusion Administrator. No transactions or orders were committed.
The CP duplicate record check formula is either invalid or missing. The default formula will be used.

Overwriting and Updating Data

Do you want to overwrite/update x?

Do you want to overwrite the existing <institute prompt> address information and flowdown? (Y/N)
Do you want to update the existing <chapter> assignment based on the new ZIP code? (Y/N)
Do you want to overwrite the existing <institute prompt> Name and Address? (Y/N)
A local copy of this file already exists on your system. Do you want to overwrite the local copy? (Y/N)
A file with that name has already been uploaded. Do you want to overwrite the file?

Save/Restore

No changes were saved. Please notify your system administrator.
The transaction was not saved. Please contact your system administrator.
The transaction was not deleted. Please notify your system administrator.
Database error. Donor name/address edits were not saved.
Database error. Soft Credit name/address edits were not saved.
The record was not added. (Note: Don’t use “insert”.)
The order was not added.
To save the current record, enter a value in one of the following fields: <name of field>, <name of field>, or <name of field>.
To save the current record, enter a value for <name of field>.
Do you want to save the changes to the <filename> activity attachment? (Y/N/Cancel)
The order has been canceled. Do you want to restore the order?
The product was not added. Please notify your system administrator.

Duplicates

Suspect duplicate list for: <Last, First>. Select Yes to continue with the current record. Select No to clear new information.

Encryption

iMIS cannot log in to the server because encryption is not available. Select OK to exit and:
- For Windows 2000, install SP2.
- Re-install iMIS ActiveX components.
The system is about to begin upgrade procedures, including irreversible encryption operations. Do you have a current backup that you know can be restored? Yes/No
If you do not have a current backup of your database and there is a system failure during the encryption operations of this upgrade, DATA WILL BE LOST. Proceed with upgrade? Yes/No

General

Continue?

Invalid Action

Do x before y.

Member/contact search is not available when editing is in progress. Save your edits, then perform the search.
Set up the default transaction account before exporting.
Set up the transaction retention period before purging transactions.
Select an open batch with an effective date that matches the billing run date before proceeding.
Select the “Pay a downpayment” option on the Installments tab before entering payment information.
Save edits in associated applications before saving to the iMIS database.
Load a meeting application before printing meeting reports.
Specify a Gift Amount before selecting a Matching Plan.
Enter line items before completing this transaction.

This x cannot be edited/delete/saved because y.

This credit card payment cannot be edited because it is being held for processing.
This event cannot be logged because the file <path, filename> cannot be opened.
This gift cannot be edited because a receipt has been issued.
This gift cannot be edited because a reminder has been sent.
This gift cannot be deleted because a reminder has been sent.
This pledge cannot be edited because a reminder has been sent.
This pledge cannot be deleted because a reminder has been sent.
This pledge cannot be edited because a payment or adjustment has been applied.
This record cannot be deleted because it has dependent records.
This record cannot be deleted because it has an open AR balance.
This record cannot be deleted because it has an open order balance.
This reminder cannot be sent because the batch has not been posted.
This reminder cannot be sent because no data has been selected.
This reminder cannot be sent because the matching amount for this plan is zero.
This transaction cannot be edited because it has been posted to an external GL system.
This transaction cannot be edited because edits are allowed only on the date of authorization. {Where space is limited: Edits are allowed only on the date of authorization.}
This transaction cannot be deleted because deletions are allowed only on the date of authorization. {Where space is limited: Deletions are allowed only on the date of authorization.}
This transaction cannot be edited because the credit card payment has been captured. {Where space is limited: This transaction cannot be edited because the payment has been captured.}
This transaction cannot be deleted because the credit card payment has been captured. {Where space is limited: This transaction cannot be deleted because the payment has been captured.}
A row of data from the <table> window cannot be saved because the <field> value was empty.
This order cannot be deleted because it has been invoiced.
This warehouse cannot be deleted because there is an open order associated with it.
The handling charge cannot be automatically calculated because the Automatic Calculation of Handling Charge option is not enabled.
Cannot switch to single warehouse option because the inventory warehouse does not match the default warehouse.
Your checkout basket contains functions which conflict. Edit your basket to delete conflicting functions.
For security reasons, files with the following extensions are not allowed in the document archive: [list]. Rename the file with a different extension.

System

Database

The <number> ID cannot be loaded. The ID may have been deleted from the database.

Printing

The selected printer is not available. Do you want to select a different printer?

Shutdown

The Customer Portfolio is shutting down due to an internal error. Please contact your system administrator.
The server type is not recognized. iMIS is shutting down. Please contact your system administrator.

Startup

The system cannot not locate the service: [fControlName]. <Perform action>.
Error opening iMIS Standard Data file (IMISSTD.DF1). The file's read-only attribute may be set. Select OK to exit.

Tables

A row in the Label Preferences table could not be saved because the label preference code <code> has already been used.

Versions/Licenses

Each portion of the version number must be four digits or fewer.
The version number has been changed to "&strMajorVer&"."&strMinorVer&"."&strRevisionVer".
The version of this software ([lvVersion]) does not match the database you are using ([System_Control.Version]). Update your database or contact your system administrator.
The maximum number of records for this installation has been reached.
The system has detected that the version of your software (#.##.##.##) does not match the version of the database (#.##.##.##). Do you want to update the database? Yes/No
A new iMIS workspace cannot be started. You may have exceeded your license count. Select OK to exit.

Web Browser

A web browser is not installed. Contact your system administrator.

MS Word Integration

Word templates cannot be accessed because the QuickLetter system is enabled.

Workflow

Incomplete tasks

Complete or cancel your task before going to another tab.

Instructions

Select OK to mark the order as shipped.
There is an overpayment of <amount>. Select Yes to confirm the creation of an AR item. Select No to cancel the process.
{For a single step}

Log in to iMIS as an administrator to insert logins.
{For two or more steps}

To update users for the new security model:

1. Log in to iMIS as an administrator.

2. Select User> Password Maintenance> Update All Logins.
This report ranks the top 100 donors only. Use the Top Donors Summary report for more donor information.

Unsaved changes

You have unsaved changes in x; save or cancel them before doing y.
You have unsaved changes in your open record; save or cancel them before opening another record.
You have unsaved changes in your open record; save or cancel them before proceeding with Search.
You have unsaved changes in your open record; save or cancel them before proceeding to the next record.
You have unsaved changes in your open record; save or cancel them before changing the Type.
You have unsaved changes in your open record; save or cancel them before refreshing the records.
You have unsaved changes; save or cancel them before going to another tab.
You have unsaved changes in your tab preferences profile; save or cancel them before exiting this window.

iMIS Community