What does a good error message look like?

It’s not easy to write good error messages.

Good error message is self educational and can easily pass "2:30am in the morning sanity test"

It's easy to identify a good error message

One of my mentors many years ago told me, “it’s easy to determine if an error message is good. First write it. One week later, wake up at 2:30 in the morning and try to understand it. If you can easily understand what the error message indicates, then the error message passes the test of being a good one”.

It’s true.

Best-of-breed error messages share these attributes:

– Unique component or caller identifier + a unique number

– Severity level: I = informational, E = error, W = warning,

– Error description (which passes the ‘2:30 in the morning sanity test’)

– Action taken by the system as a result of the error

– Action recommended to the user – if applicable

– Detailed diagnostic information (if enabled) to quickly determine the root cause and reduce diagnostic time to the bare minimum

This is a real error message which has been subject of a recent design discussion.

Before:

– “Error: transmission failed”

After:

– TRX-SEND-0012E Transmission failed. File=<name>, Source=<location>,Destination=<new location>. 10 MB of 50MB transmitted. Transmission will restart in 3 minutes. No action required from the user.

This message clearly passes the ‘2:30am in the morning sanity test’. No one in the software engineering team will get a call from the client or technical support team.