101 to 404:s How to write a great error message

A talk I gave at Write the Docs in Prague 2019 on writing error messages.

Transcript

1. How to write great error messages 
 @scottydocs 101 to 404s James Scott
2. How to write great error messages 
 @scottydocs 101 to 404s James Scott
3. This page is too large to be shown completely. ! This cost $50,000!
4. ERRORS EVOKE EMOTIONS
6. • Notification that something went wrong
 • Explanation of why it went wrong
 • Solution to the problem. 
 @scottydocs What is an error message?
7. • Unclear text that creates confusion • Badly written or contain jargon • Dead ends with no resolving steps. In reality… 
 @scottydocs
8. Programmer Administrator Everyone Audience: Who is the error for?
9. Problem exists between keyboard and computer. PEBKAC error: Be humble
10. Be humble: Apologise? Sorry, there seems to be a problem…
11. You have entered an illegal object name character. Remove the illegal object name character. Don’t make users feel like criminals!
12. Oops! Something went wrong… Be helpful: Don’t create dead ends! Please try again or check out our help centre. Oops! Something went wrong. 1 2
13. You have used the extension “.png” at the end of a name. The standard extension is “.png”. Use .png Use .png Cancel Be helpful: Avoid ambiguity
14. Something is wrong with your requested resources. Fill it properly and try again. Ambiguity creates questions What? Which? How?
15. Your API path must be unique. Ambiguity creates questions Choose a new path and try again. Which What How
16. • 8 words or less, readers understood 100%
 • 14 words readers understood 90%
 • 43 words + readers understood < 10%. Be concise 
 @scottydocs
17. Error: Password was not validated - invalid password - min character groups of 3 not fulfilled (error code: 400) Be clear: Avoid jargon Your password must contain: • A lowercase character • An uppercase character • A special character.
18. Be human: Avoid jargon 1 3 2 Resolution of dependency failed. Unhandled exception occurred in component of your application.
19. Be human: Show empathy
20. Be human: Use humour?
21. Whoops, you found a dead link… Should you use humour?
22. Humour: Frequent errors Bad, bad server. No donut for you. Unfortunately, the orkut.com server has acted out in an unexpected way. Hopefully, it will return to its helpful self if you try again in a few minutes.
23. Goose egg. There’s no information available. Humour: Translation issues
24. Humour: Easter eggs 
 @scottydocs
25. • Use humour with caution • Avoid for frequent or frustrating errors
 • Beware of translation issues • Best as an Easter Egg. Humour: Conclusion 
 @scottydocs
26. 
 @scottydocs Fail pets: Error mascots
27. Fail pets: The Fail Whale 
 @scottydocs
28. Fail pets: Symbols of failure?
29. Pros • Evoke empathy • Reduce frustration • Enable rapid recognition. Cons • Make errors more memorable • Association with failure • Translation issues. Fail pets: Pros & Cons 
 @scottydocs
30. Colour: Considerations OXYGEN 3% WARNING
31. Colour: Translation issues
32. Colour: Accessibility (A11y) Warning: User must be an admin Success: You created a password Error: There was a system error
33. A11y: Error forms 1. Adopt an “errors on top” approach. 2. Use clear + straight-forward language.
 3. Expose error to assistive technology. 
 @scottydocs
34. A11y: ARIA 
 @scottydocs ARIA (Accessible Rich Internet Applications) aria-describeby <label for"psswd">Password:</label> <input type="password" id="psswd" aria-describeby="psswd-help"> <div id="psswd-help"> Password must be at least six characters </div> ***** Password: * Password must be at least six characters
35. A11y: Check for yourself! www.a11yproject.com
36. hack noun a strategy or technique for managing one’s time or activities more efficiently My solution 
 @scottydocs
37. H A C K Helpful Humble Human Humour Audience Accessibility Concise Clear Knowledge
38. Sorry, this is the end of my presentation. Enjoy the rest of Write the Docs Prague! :( 
 @scottydocs
39. 1. Real-time measurement of human salivary cortisol for the assessment of psychological stress using a smartphone - Choi, Kim, Yang, Lee, Joo and Jung (December 2014) 2. Non-Fatal Errors: Creating Usable Effective Error Messages - Emily Wilska. 3. Developing Windows Error Messages (O’Reilly)- Ben Ezzell. 4. Windows Dev Center Guidelines on Error Messages - Microsoft. 5. Towards a more civilised design: studying the effect of computers that apologise - Jeng-Yi Tzeng (January 2004) 6. The Effect of Apologetic Error Messages on User’s Self-Appraisal of Performance — Akgun, Cagiltay and Zeyrek (September 2018) 7. Information Technology Exception Messages: An investigation of compliance with the normative standards of warnings- Amer and Maris (September 2007) 8. Reader’s Degree of Understanding - The American Press Institute. 9. Technical Communication - Mike Markel (December 2014) 10. How to make brands sound human - Anna Pickard (June 2019) Resources
40. 11. I'm Feeling Lucky: The Confessions of Google Employee Number 59- Douglas Edwards. 12. Translating Humour - The Problems of Translating Terry Pratchett - Linda Broeder (2007) 13. The Evolution of Fail Pets - Sean Rintell (November 2011). 14. The Quiet Death of the Tech Company Mascot - Bryan Lufkin (April 2014) 15. The Experience of Enchantment in Human-Computer Interaction - McCarthy, J., Wright, P., Wallace, J. & Dearden, A. (2005) 16. Killing the Fail Whale with Twitter’s Christopher Fry - Wired (November 2013) 17. A study of the metaphor of “Red” in Chinese Culture - Qiang Huang (November 2011). 18. How to Provide Accessible Error Identification - Level Access. 19. Error Messages: Being Humble, Human and Helpful - Kate Voss (2017 Resources