Write the Docs Prague

How to write the perfect error message- WritetheDocs 2019, Prague

on September 16, 2019

We are honored to partner with #writethedocs, Prague. This year is very important for us in achieving the biggest milestones in our business journey and laying strong marketing strategies. Last night we landed at Prague to attend #Writethedocs event. 

There is an enthusiastic, supportive atmosphere created on open days by #writethedocs team and I just believe this was where we meant to go.

In this article, we have put together the morning talks covered on day 1 of the event- September 16th 

Introduction to #Writethedocs

This is the sixth year in a row hosting the conference in Europe to great success! The audience at the conference at defined as documentarians meaning it is more than just technical writers, you can be from any part of the industry who involves in content development for communication.

day 1 doc

Apply pac-man rule during networking.

Every group should leave room for at least one person to join” a great idea, we have seen people walk away when the group is already busy and not welcoming new onE


James Scott – How to write the perfect error message

What is an error message?

Error,  message is a piece of documentation that comes in when something goes wrong. The three main elements of Error message are:

  • Notification that something went wrong
  • Explanation of why it went wrong
  • Solution to the problem

Common issues with the Error Messages

  • Unclear text that creates confusion
  • Contain jargons
  • Dead ends with no resolving steps

Error messages are micro-copy, but they deserve more attention than they get. Bad error messages can result in unhappiness and in bad reports on social media.

How to improve the error messages?

Step #1 Define the Audience

Who is the error message for? if you are writing a piece of documentation that informs the error and steps to solve who is the reader a programmer, an administrator or is it for everyone? Be clear in defining the audience

Step#2 Be Humble

Being humble means you should also be ready to apologise this means more human to human interaction

Step #3 Avoid accusatory Language

Don’t make users feel like criminals. “You have entered an illegal object name characters” – Remove “illegal”

Step #4  Avoid Dead end error Messages

Give the user some solution about what to do next. You can also redirect them to help centre with a link

Step #5 Avoid Ambiguity

Ambiguity creates questions. ex: “Something is wrong with your requested resources”

Step# 6 Be concise

We have limited space for error message so keep it short and simple. Use 8 words or less.

Step # 7 Be clear. Avoid jargons. 

Avoid being incredibly robotic and use human language. Show empathy to the users. For Example: “Password was not validated, error code 400”

Step#8 Use Humour with caution

Be careful when using humour language. It may be risky, you need to see cultural aspects and translation challenges. Sometime it might make sense to only a small group, you might lose context. Avoid frustrating errors.

The trend of Fail Pets: Twitter’s Fail Whale as fail pets. Fail pets are of particular interest in brand recognition through earned media. However, that same recognition carries the danger of highlighting service failure.

Step#9 Use of Colour has translation issues

Colour RED is generally used for failures, which could be dangerous. In China it’s treated with positivity, in the west it’s treated with danger. Accessibility is another issue, you need to consider colour blindness and use icons like ticks, triangle

Step#10 Check for accessibility challenge

Dealing with error messages can be frustrating for most users.

  1. Adopt “error on top” approach
  2. Use clear+straight forward language
  3. Expose error to assistive technology

Check  www.a11yproject.com for accessibility resources

Writing error messages that explicitly and distinctly addresses each of the errors and share the information to the end-user helps the software attract and keep more users, who will use it more effectively – and that is one of the things the business want most of all.