zError Messages

“The best error message is the one that never shows up” — Thomas Fuchs

A good error message has three parts:

1. Problem identification
2. Details on what caused the error and a solution, if possible
3. Use the user's language

Microcopy matters! Strive to use the language our developers use and make technical stuff as clear as we can.

Writing guidance for error messages

A well-written error message starts with a general statement of the problem and then gives a concise description of what went wrong.

1. Are clear and unambiguous.
2. Are short and meaningful with a clear idea of the problem and how to resolve it.
3. Use simple and plain language and avoid technical jargon. Use accurate terminology, see Word List.
4. Use present tense.
5. Is humble and conveys the issues gracefully to the user without blaming them for their actions. See Tone and Content.
6. Use positive words, are polite and friendly.
7. Provide appropriate actions and give directions on how to get out of the erroneous situation
8. Are specific to the action and relevant with information on where to go and include steps to resolve it
9. Are a single, clear, sentence. Use sentence case (do not use UPPERCASE) and end with a period (.)

Error message resources

Compiler Errors for Humans How to Write Good Error Messages Atlassian: Writing Error Messages