How to write great error messages 
 @scottydocs 101 to 404s James Scott 

How to write great error messages 
 @scottydocs 101 to 404s James Scott 

This page is too large to be shown completely. ! This cost $50,000! 

ERRORS EVOKE EMOTIONS 

No content

• Notification that something went wrong
 • Explanation of why it went wrong
 • Solution to the problem. 
 @scottydocs What is an error message? 

• Unclear text that creates confusion • Badly written or contain jargon • Dead ends with no resolving steps. In reality… 
 @scottydocs 

Programmer Administrator Everyone Audience: Who is the error for? 

Problem exists between keyboard and computer. PEBKAC error: Be humble 

Be humble: Apologise? Sorry, there seems to be a problem… 

You have entered an illegal object name character. Remove the illegal object name character. Don’t make users feel like criminals! 

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 

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 

Something is wrong with your requested resources. Fill it properly and try again. Ambiguity creates questions What? Which? How? 

Your API path must be unique. Ambiguity creates questions Choose a new path and try again. Which What How 

• 8 words or less, readers understood 100%
 • 14 words readers understood 90%
 • 43 words + readers understood < 10%. Be concise 
 @scottydocs 

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. 

Be human: Avoid jargon 1 3 2 Resolution of dependency failed. Unhandled exception occurred in component of your application. 

Be human: Show empathy 

Be human: Use humour? 

Whoops, you found a dead link… Should you use humour? 

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. 

Goose egg. There’s no information available. Humour: Translation issues 

Humour: Easter eggs 
 @scottydocs 

• Use humour with caution • Avoid for frequent or frustrating errors
 • Beware of translation issues • Best as an Easter Egg. Humour: Conclusion 
 @scottydocs 


 @scottydocs Fail pets: Error mascots 

Fail pets: The Fail Whale 
 @scottydocs 

Fail pets: Symbols of failure? 

Pros • Evoke empathy • Reduce frustration • Enable rapid recognition. Cons • Make errors more memorable • Association with failure • Translation issues. Fail pets: Pros & Cons 
 @scottydocs 

Colour: Considerations OXYGEN 3% WARNING 

Colour: Translation issues 

Colour: Accessibility (A11y) Warning: User must be an admin Success: You created a password Error: There was a system error 

A11y: Error forms 1. Adopt an “errors on top” approach. 2. Use clear + straight-forward language.
 3. Expose error to assistive technology. 
 @scottydocs 

A11y: ARIA 
 @scottydocs ARIA (Accessible Rich Internet Applications) aria-describeby Password: ***** Password: * Password must be at least six characters 

A11y: Check for yourself! www.a11yproject.com 

hack noun a strategy or technique for managing one’s time or activities more efficiently My solution 
 @scottydocs 

H A C K Helpful Humble Human Humour Audience Accessibility Concise Clear Knowledge 

Sorry, this is the end of my presentation. Enjoy the rest of Write the Docs Prague! :( 
 @scottydocs 

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 

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