This document provides best practices for writing error messages. It recommends that error messages be specific about what happened, constructive by indicating how to fix the issue, understandable by avoiding technical jargon, positively tone by not blaming the user, use plain English, be consistent in terminology, avoid using red colors, and can include humor to reduce frustration. The document also provides examples of good and bad error messages and recommends using active voice, present tense, and descriptors to clarify meaning. The overall goal is to write error messages that clearly explain the problem and solution without irritating the user.

1. ERROR MESSAGES
HOW TO WRITE

3. BEST PRACTICES
ERROR MESSAGES

4. BE SPECIFIC
Explain to user what has happened and why.
BEST PRACTICES

6. Absolutely not.

7. Yes, why?

8. BE CONSTRUCTIVE
Say what needs to be done to fix this
mistake.
BEST PRACTICES

11. BE UNDERSTANDABLE
Don’t use some technical bullshit. No one
cares (and understands).
BEST PRACTICES

12. Ahh, those terrible media ids again.

13. USE A POSITIVE TONE
Avoid condemnation. Be polite and don’t
blame the user.
BEST PRACTICES

15. USE PLAIN ENGLISH
Use language that is concise and accurate.
Avoid any unnecessary words.
BEST PRACTICES

16. BE CONSISTENT
Use consistent grammar, terminology and
abbreviations.
BEST PRACTICES

17. DON’T USE RED COLOR
Some users are color blind. Also, this color
irritates people more.
BEST PRACTICES

18. Well, shit.

19. DON’T BE AFRAID OF HUMOUR
Use humour (wisely) to reduce user’s
frustration.
BEST PRACTICES

21. YEAH, KIND OF.

23. BEST PRACTICES
GREAT MESSAGE EXAMPLE

24. BEST PRACTICES
GOOD MESSAGE EXAMPLE

25. BEST PRACTICES
WHAT TO AVOID
▸ Negative phrasing, such as “wrong”, “bad”, “invalid" and “illegal”
▸ Word “please”. It can be interpreted to mean that a required
action is optional
▸ Anthropomorphism - do not imply that the software has feelings
or thoughts
▸ Generic phrases, such as “unexpected error”.
▸ Vague wording - give specific names and locations of the objects
involved

26. BEST PRACTICES
WORDS TO AVOID

27. BEST PRACTICES
LANGUAGE - BEST PRACTICES
▸ Use the active voice if possible -> System doesn’t recognize
your email address.
▸ Use the passive voice to describe the error condition -> This is
because of a server error.
▸ Use the present tense to describe the conditions that caused
the problem -> Our server is down and doesn’t accept new
logins.
▸ Insert descriptors before a term to clarify the meaning of the
sentence
Specify ID when Detect is set to No. Specify the ID parameter if the Detect option is set to No.

28. THE BEST ERROR MESSAGE
IS THE ONE THAT NEVER
SHOWS UP.

29. SOURCES
SOURCES
▸ https://uxplanet.org/how-to-write-a-perfect-error-
message-da1ca65a8f36
▸ https://medium.com/@thomasfuchs/how-to-write-an-error-
message-883718173322
▸ http://www.ihearttechnicalwriting.com/write-error-
messages/