Tailor the error message to the target audience. That is:
- Use appropriate terminology for that target audience.
- Be mindful of what the target audience knows and doesn’t know.
Beware of the curse of knowledge when writing error messages. A term familiar to you might not be familiar to your target audience. For example, the following error message contains terminology appropriate for a target audience of ML experts. If the target audience includes a significant number of people who aren’t ML experts, then the error message is mystifying:
Recommended for ML experts only
Exploding gradient problem. To fix this problem, consider gradient clipping.
Now compare the following two error messages. The first error message contains technical truth, but terms like server, client, farm, and CPU are not going to help most consumers:
Inappropriate for shoppers
A server dropped your client’s request because the server farm is running at 92% CPU capacity. Retry in five minutes.
The second error message is more suitable (and comforting) for a non-technical audience:
Appropriate for shoppers
So many people are shopping right now that our system can’t complete your purchase. Don’t worry—we won’t lose your shopping cart. Please retry your purchase in five minutes.
Multiple choice exercise
Which audience(s) is the following error message appropriate for?
- This app does not support JPG files. You may only upload SVG or PNG files.
Software Engineers, System Administrators, and technical end-users
Inappropriate for any audience.
People using an app to upload receipts.