101 to 404s: How to write great error messages


Error messages are such a small and innocuous part of documentation that they sometimes don't always receive the care and attention that they deserve. Even the shortest error message can evoke far stronger, negative emotions in your end users than the majority of your documentation. If you get your error messaging wrong, it can not only lead to poor user experience and customer frustration but also low product satisfaction, and in worst cases, ridicule on social media.

After being asked by a developer for advice on how to write error messages, I found there wasn't really a definitive guide I could recommend so I ended up doing some research of my own and put some rough guidelines together. My talk will cover the three Hs (Be Helpful, Be Human, Be Humble), as well as the pros and cons of using humour and the risks of creating error mascots" or "fail pets" to reflect your brand. I will share some examples of error messages in the wild, highlighting where some companies have learned from their mistakes and corrected their error messages. I will also discuss sentence length and how it impacts user comprehension before touching upon colour and design; sharing my research into colour psychology, cultural interpretations of colour and its impact on accessibility.

  • Conference: Write the Docs PRAGUE
  • Year: 2019

About the speaker

James Scott