Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

F4004183ff78e0cf67bb6e8a7d469702?s=47 James Scott
September 16, 2019

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.


James Scott

September 16, 2019


  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!

  5. None
  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… 
  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 
  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 

  25. • Use humour with caution • Avoid for frequent or

    frustrating errors
 • Beware of translation issues • Best as an Easter Egg. Humour: Conclusion 
 @scottydocs Fail pets: Error mascots

  27. Fail pets: The Fail Whale 

  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 
  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. 
  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 
  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! :( 
  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