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.
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.
- Adopt “error on top” approach
- Use clear+straight forward language
- 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.