How to write the perfect error message

Error messages are seemingly so innocuous but they’re actually incredibly important in ensuring good UX and keeping your end user happy. A good error message informs your customers what went wrong, why it went wrong and what they can do to resolve it. Microsoft’s Windows developer centre guidelines state the following:

 “Effective error messages inform users that a problem occurred, explain why it happened, and provide a solution so users can fix the problem. Users should either perform an action or change their behavior as the result of an error message.”

If you get that wrong, it can not only lead to frustration and low product satisfaction but in the worst cases you might lose credibility with your customers or end up being ridiculed on social media.

Although getting error messages right isn’t always easy, there are simple steps to follow to ensure you don’t leave your end users in the dark (or rolling around on the floor in fits of laughter).

Check your spelling and grammar

Accurate spelling and grammar is vital in terms of ensuring your audience understands the message you’re trying to get across. The professional quality of your external facing content also reflects the professional quality of your product and your brand.

Although spelling mistakes and typos can sometimes be quite harmless and funny, if your content lacks accuracy, you also run the risk of causing confusion. If you’re not confident about your choice of wording, ask a technical writer or content specialist for help.

Be specific

Default error messages like “There has been an error” or “An error has occurred” are really unhelpful. Don’t just tell your end users that something happened, tell them why and what they can do to fix it.

Dubbed as “the least helpful error in Windows history”, Microsoft presented users with an error message that simply stated “Something happened” when they tried to install Windows 10:

Ahh something happened…

This error message was so bad it became something of a social media meme with users ridiculing how unhelpful it was. The solution, which was revealed by someone on Reddit, was as simple as changing your language settings but the text was so ambiguous it could have remained a total mystery.

Provide the right amount of detail

If you can explain what has gone wrong, then add a description in non-technical terms so your user understands the context. It’s great to be polite but simply posting an error message saying “Sorry” or “Oops” doesn’t really help anyone.

If you’re going to “sorry”, follow it up with an explanation of what happened and offer some actionable steps so the user can resolve the problem.

Avoid jargon and developer speak

Remember that you aren’t talking to another developer. Your end user doesn’t read code or care about the internal processes involved in making your product work. Break down what’s going on in simple terms that anyone could understand.

In this example where the user was trying to create a new password, the validation error message text is overcomplicated and contains developer jargon.

It would have been much better to say something like: Please try again. Your password needs to contain both lower and upper case characters and a special character.

Another example of bad developer jargon appears in the Microsoft dev center guidelines under the heading “incomprehensible error message”:

Don’t be a robot 🤖

What’s an MM error? What’s a standard FsRtl filter? What does this 0xC00000EA code mean? This error message might explain the problem from a developer’s perspective but it leaves you with more questions than answers.

Be a human and friendly

While you’re thinking about how to avoid using jargon and writing in developer speak, it’s also good to remember to be human. Your end users don’t want to feel like they’re being spoken to by a robot. Remember to speak their language and be friendly in your messaging.

This error message from the Meta Stack Exchange site is a good example of how you can be human and friendly in your messaging:

“It’s not you, it’s us…”

Sure, it isn’t particularly specific but it is apologetic, it makes it clear the error was not your fault and informs you that the error has been recorded and someone will look at it.

Be clear and unambiguous

Ambiguity doesn’t help anyone. Presenting your users with some vague message that offers no practical information about what is going on and what they can do to solve the problem is really unhelpful.

If your error message is confusing, it has failed its primary objective. Think about what you are trying to tell the end user, how they will process that information and write it in the clearest possible terms.

If you’re unsure, get a tester or someone in a non-technical department to read the text and see if they can make sense of it.

Be concise

Users do not want to read your life story in an error message. If something has failed, an error message should be a short, concise piece of text that informs the user what went wrong and provide a potential resolution to the problem.

So much text!

Research by the American Press Institute found evidence that shorter sentences resulted in greater understanding:

  • For sentences that were 8 words or less, readers understood 100% of the information.
  • For sentences that were 14 words long, readers understood 90%.
  • For sentences that were 43 words or longer, comprehension dropped to less than 10%.

On that basis, there is an argument for keeping your sentences short. That is the recommendation of author Martin Cutts, who offers the following advice in the Oxford Guide To Plain English:

“Over the whole document, make the average sentence length 15–20 words…More people fear snakes than full stops, so they recoil when a long sentence comes hissing across the page.”

Voice and tone

Choosing the right voice and tone for your error messages is really important. You shouldn’t use an accusatory tone that makes the user feel like they’ve done something wrong or that the error is their fault:

Don’t make your user feel like a criminal!

You might want to consider ensuring the tone you use is in keeping with your brand. Slack is known for being quite playful with their messaging:

Anna Pickard, Slack’s head of brand communications, said their friendly, sometimes playful tone of the editorial copy was a vital part of supporting the product and making users feel like they’re talking to a friendly co-worker:

“It is sometimes funny, sometimes serious, sometimes just plain and informative, but throughout, it should feel like nothing more than a person, talking to another person. Human to human.”

Apple’s Human Interface guidelines advise using a friendly tone helps to avoid sounding accusatory or judgemental:

“People know that alerts notify them about problems and dangerous situations. As long as you use a friendly tone, it’s better to be negative and direct than positive and oblique.”

Add humour when appropriate

Having a sense of humour is good but it normally only works if you’re helping the end user at the same time. However, sometimes trying to funny can fall short of the mark if your error message isn’t particularly helpful:

Github’s 404 page mimicking Obi-Wan Kenobi’s famous quote from Star Wars is a nice example of combining humour and knowing their audience:

In Mailchimp’s content style guide they recommend only trying to be funny when it comes naturally and not forcing it when it’s inappropriate:

“…feel free to be funny when it’s appropriate and when it comes naturally to you. But don’t go out of your way to make a joke — forced humor can be worse than none at all. If you’re unsure, keep a straight face.”

Think about colour and design

It is important to think about the colour and design of your error messages so they are UX friendly and accessible to all of your users’ needs. Don’t choose colours for your font and background that are too similar or will be difficult for people with colour blindness to distinguish between:

Don’t use colours that clash or would be difficult for people with colour blindness to read.

Some general guidelines to follow are:

  • Avoid using font and background colours that clash.
  • Think about accessibility. Users with colour-blindness might not be able to distinguish between shades of red and green.
  • Be consistent if you are going to use colours to denote different types of alert. E.g. Green for a success message, yellow/orange for transient warnings and red for an error message.
  • Choose a font and background colour that contrast nicely.

Red is the most common choice for error messages and associated icons for a reason. In his paper about colour associations, psychology professor Dr Arlen C. Moller noted how red often conveyed negative information in everyday life and had objective connotations with danger in the form of fire and blood.

Meanwhile research on colour psychology by professor Andrew J Elliot from the University of Rochester found that people’s attention was drawn to the colour red much faster than other colours:

“In research on color and selective attention, red stimuli have been shown to receive an attentional advantage… Participants’ visual search times were faster for desaturated red (relative to several other colored) targets”

Summary

In summary, when creating your next error message remember to think about the following things:

  1. Spelling and grammar. Accuracy is important.
  2. Be specific. What happened?
  3. Provide the right amount of detail.
  4. Avoid jargon and developer speak.
  5. Be human and friendly.
  6. Be clear and unambiguous.
  7. Be concise. If in doubt, aim for 15–20 words per sentence.
  8. Choose the right voice and tone.
  9. Add humour but only when appropriate.
  10. Think about colour and design.

TL;DR —Write your error messages in concise, friendly and non-technical language that everyone can understand. Otherwise they’re pretty useless.

Resources:

  1. Microsoft Windows Dev Center guidelines on Error Messages: https://docs.microsoft.com/en-us/windows/desktop/uxguide/mess-error
  2. “Windows 10’s ‘Something Happened’ error is turning into a meme”, WIRED article: https://www.wired.co.uk/article/windows-10-something-happened-error
  3. How to make your copy more readable: Make sentences shorter: http://prsay.prsa.org/2009/01/14/how-to-make-your-copy-more-readable-make-sentences-shorter/
  4. Slack’s Editorial Soul: Anna Pickard on writing the brand experience: https://www.contagious.com/news-and-views/slacks-editorial-soul-anna-pickard-on-writing-the-brand-experience
  5. Apple’s Human Interface Guidelines on Alerts: https://developer.apple.com/design/human-interface-guidelines/macos/windows-and-views/alerts/
  6. Voice and Tone: Mailchimp Content Style Guide: https://styleguide.mailchimp.com/voice-and-tone/
  7. Basic Hue Meaning Associations: Arlen C. Moller: http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.438.157&rep=rep1&type=pdf
  8. Color and psychological functioning: a review of theoretical and empirical work: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4383146/

Will AI reduce the need for technical writers?

The late Stephen Hawking famously said that artificial intelligence would be “either the best, or the worst thing, ever to happen to humanity.” As a technical writer documenting AI technology, I’d like to believe it would be the former and it’s fair to say there have already seen positive signs about how AI might shape and assist with documentation in the future.

A number of tech companies have already dipped their toes into the water, with some developing AI-assisted, predictive content generation and others harnessing machine learning to predict the help content the end-user is looking for.

AI-assisted content

Google introduced its natural language processing development, Smart Compose, to help Gmail users write emails in May 2018. They combined a bag-of-words (BoW) model with a recurring-neural-network (RNN) model to predict the next word or word sequence the user will type depending on the prefix word sequence they wrote previously.

model3
The Smart Compose RNN-LM model architecture.

Smart Compose was trained with a corpus of billions of words, phrases and sentences, and Google carried out vigorous testing to make sure the model only memorised the common phrases used by its many users. The Google team admits it has more work to do and is working on incorporating their own personal language models that will more accurately emulate each individual’s style of writing.

Arguably one of their biggest challenges they face is reducing the human-like biases and subsequent unwanted and prejudicial word associations that AI inherits from a corpus of written text. Google cited research by Caliskan et al which found that machine learning models absorbed stereotyped biases. At the most basic level, the models associated flower words with something pleasant and insect words with something unpleasant. More worryingly, the research found the machine-learning models also adopted racial and gender biases.

f1.large

The research found that a group of European American names were more readily associated with pleasant than unpleasant terms when compared to a batch of African American names. Researchers also found inherited biases included associating female names and words with family and the arts while male names were associated with career and science words. Yonghui Wu, the principal engineer from the Google Brain team, said: “…these associations are deeply entangled in natural language data, which presents a considerable challenge to building any language model. We are actively researching ways to continue to reduce potential biases in our training procedures.”

AI-assisted spelling and grammar

With 6.9 million daily users, one of the most common tools people are using to assist the accuracy of their spelling and grammar is Grammarly. The company are experimenting with AI techniques including machine learning and natural language processing so the software can essentially understand human language and come up with writing enhancements.

crisp-writing-alter-ego-communications

Grammarly has been training different algorithms to measure the coherence of naturally-written text using a corpus of text compiled from public sources including Yahoo Answers, Yelp Reviews and government emails. The models they have experimented with include:

  • Entity-based model – Tracks specific entities in the text. For example, if it finds the word “computer” in multiple sentences it assumes they are related to each other.
  • Lexical coherence graph – Treats sentences as nodes in a graph with connections (“edges”) for sentences that contain pairs of similar words. For example, it connects sentences containing “Macbook” and “Chromebook” because they are both probably about laptop computers.
  • Deep learning model – Neural networks that capture the meaning of each sentence and are able to combine these sentence representations to learn the overall meaning of a document.

Although this is still a work in progress, their long term goal is for Grammarly to not only tell you how coherent your writing is but to also highlight which passages are difficult to follow.

AI-assisted help content

Some companies have started to look at ways that AI can help with predicting and directing readers to the exact content they are looking for. London-based smart bank Monzo launched a machine-learning powered help system for their mobile app in August 2017.

monzo

Their data science team trained a model of recurring-neural-networks (RNNs) with commonly asked customer support questions to make predictions based on a sequence of actions or “event time series”. For example:

User logs in → goes to Payments → goes to Scheduled payments → goes to Help.

At this point, the help system provides suggestions relating to payments and as the user starts typing, returns common questions and answers relating to scheduled payments. Their initial tests showed they were able to reach 53% accuracy when determining the top three potential categories that users were looking for out of 50 possible support categories. You can read more about their help search algorithm here.

What does the future hold?

I think we will see more content composition tools like Smart Compose emerge but I think it will take a lot of time and work before they can be trained to effectively assist with the complex and often unpredictable user-oriented content that technical writers are tasked with producing on a daily basis.

datacenter-future-e1503509968416

I’m sure some technical writers are already using Grammarly to assist with their spelling and grammar. It can be a really powerful tool to ensure your text is not only accurate but in the future will be able to measure the coherence of your writing. I’ve dabbled with Grammarly but found it either wasn’t compatible with certain tools or prevented some of my applications from working so it became a bit of hindrance rather than an assistant for me personally. No doubt these are kinks they will iron out at some point down the line.

I do see the benefits of AI-assisted help so it would be awesome to see some more development in this area. It really could be something that saves customer support and documentation teams a lot of time in terms of predicting and directing end-users to answers before they’ve even asked a question.

So are we there yet? Not quite… but I think some very promising foundations have been laid. While some technical writers might be concerned, I think it will be a very long time before AI is advanced enough to supplant our role in the development teams. So don’t be afraid of AI, for the time being these tools are only going to make our lives easier!

GraphQL: “If there’s no documentation, people aren’t going to be able to use it…”

I recently gave a talk at the API the Docs conference in London where I was finally able to share some valuable advice about GraphQL documentation. My talk followed my journey from first being told that GraphQL was self-documenting and didn’t need documentation, to speaking to GraphQL co-creator Lee Byron in my quest for answers and receiving the words of wisdom that I was able to share at the conference.

GRaphQL
An artist’s impression of me (left) at the start of my GraphQL journey…

After initially being told by a developer that GraphQL wouldn’t need documentation, I was pretty sceptical, but as I starting researching I found numerous examples of developers advocating GraphQL’s self-documenting nature with someone even declaring that it didn’t need documentation.

Although the majority of people were fairly positive about the self-descriptive features, one tweet from a developer who was unhappy with the GraphQL documentation he had encountered made me realise I might be onto something.

🤖 What does “self-documenting” mean?

I explored what is meant by self-documenting – something written or structured in such a way that it can be understood without prior knowledge or documentation – and highlighted how the PC Magazine definition came with this caveat about subjectivity:

“It’s very subjective. However, what one programmer thinks is self- documenting may truly be indecipherable to another.” 

poor-software-quality-5454

I investigated the risks of subjectivity, how words like homographs such as “second”, “number” and “subject” can have multiple meanings and might be interpreted differently. I also shared different opinions on self-documenting code, how some people feel it is a myth and an excuse for developers to avoid writing documentation:

 

I also referred to a blog post by Write the Docs co-founder Eric Holscher who said self-documenting code was “one of the biggest documentation myths in the software industry”, adding that the self-documenting argument boils down to:

  • I made something with a specific use.
  • I gave it a name to represent that specific use.
  • It doesn’t need documentation now because it’s obvious how it works.

Holscher argued that people who believe in a world of self-documenting code are actually making it more difficult for normal people to use their software.

🔬 How intuitive is GraphQL?

To test some of these self-documenting claims, I stripped out the introductory documentation from the Github GraphiQL explorer and asked six of my colleagues (members of QA, development and documentation) to try and retrieve my name, location and avatar URL with a GraphQL query from just my Github login name.

Screenshot 2018-11-05 at 16.00.01

The results were pretty interesting with pretty much all of them struggling with the syntax and encountering fairly similar parsing errors. The amount of time it took them to formulate a query through trial and error proved to me that GraphQL isn’t actually that intuitive without some form of example query or hand-holding documentation to get you started.

The other common issue I have encountered with some GraphQL APIs was developers either failing to add descriptions or using ‘self-descriptive’ as a description for queries and fields that weren’t particularly descriptive. Some of these relied on assumed knowledge, expecting the end user to have a prior knowledge of the schema and the data it relates to.

After looking at the GraphQL spec, I found this line, which might explain why some developers are not including descriptions: “All GraphQL types, fields, arguments and other definitions which can be described should provide a description unless they are considered self descriptive.”

Docs-first-class-feature-7856.png

Whether they realise it or not, the issue is these people are unintentionally making it difficult for people to use their APIs. GraphQL co-creator Lee Byron spoke about the importance of naming at the GraphQL Summit in 2016:

“It’s really important not just to have names that are good but to have names that are self-documenting […] Naming things that adhere closely to what those things actually do is really important to make this experience actually work.”

🐴 Straight from the horse’s mouth

I thought this was pretty interesting but I still wanted a definitive answer about GraphQL documentation so I emailed Lee Byron, who also happens to be the editor of the GraphQL spec, asking him if he would answer some of my questions. To my surprise he agreed to an interview back in September. We spoke for about half an hour and he told me all about the history of GraphQL, his hopes for its development and we touched upon documentation. When I asked him about the importance of descriptions in GraphQL, he gave the following advice:

“APIs are a design problem, way more than they’re a technical problem and you know this better than anybody else if you’re working on documentation.

If there’s no documentation, it doesn’t matter how good the API is because so much about what makes an API work well is mapping well to your internal mental model for how something works and then helping explain those linkages and the details.

If you do that wrong, it doesn’t matter how good your API is, people aren’t going to be able to use it.

Lee-2

GraphQL doesn’t do that for you, it provides some clear space for you to do that.

There’s the types and the fields and introspection, you can add descriptions in places so it wants to help you but if you don’t put in the thought and you end up with a poorly designed API, that’s not necessarily GraphQL’s fault right?”

I asked Lee’s permission to use the video clip of him giving this advice during my talk as I knew it would resonate with other API documentarians and having one of the GraphQL co-creators validate what I’d set out to prove all along was a pretty awesome mic drop moment for me!

✍️ So how do we document GraphQL?

Lee Byron spoke about how GraphQL provides you with “clear space” for the documentation: the types, the fields, the descriptions and introspection. So by using self-descriptive names for the types and fields and by using good descriptions in your GraphQL schema, you make it a much more user-friendly experience for your end user. I have highlighted where descriptions appear in GraphiQL for the Star Wars API (SWAPI):

GQL-Descriptions.png

However, these descriptions will only get you so far because documentation generated dynamically from your schema is never going to be very human.

Former technical writer and developer Carolyn Stransky spoke about this issue and a number of other blockers she encountered while trying to learn GraphQL at the GraphQL Finland conference. These included “an unhealthy reliance on the self-documenting aspects of GraphQL”, unexplained jargon and assumed knowledge. She felt most of these issues could have been easily prevented if more care and consideration had gone into the documentation.

knowledge-is-power
Carolyn Stransky cited assumed knowledge and unexplained jargon as blockers she encountered while trying to learn GraphQL.

I wanted to see what other technical writers were saying about GraphQL documentation but given the technology is so new, my questions on the Write the Docs Slack channel and other forums went unanswered. However, I did find a couple of good resources.

Andrew Johnston, who works on the GraphQL documentation at Shopify, spoke about the importance of providing on-boarding or “hand-holding” documentation for people who are new to GraphQL and not just assuming your end users will know how to formulate queries and mutations.

Technical writer Chris Ward wrote a blog post about whether GraphQL reduces the need for documentation and concluded that while it “offers a lot of positives on the documentation front”, documentarians should treat it just like any other API. He wrote:

“Documenting API endpoints explains how individual tools work, explaining how to use those tools together is a whole other area of documentation effort. This means there is still a need for documentation efforts in on-boarding, getting started guides, tutorials, and conceptual documentation.”

So my conclusion was GraphQL can be self-documenting but only if you put in the effort to give your fields and your types self-descriptive names, if you add good descriptions and if you provide adequate supporting documentation, especially for people who are new to GraphQL. Ultimately I think technical writers have a pretty important role to play in documenting GraphQL and ensuring the experience works, to repeat Lee Byron’s advice – if your API doesn’t have any documentation then people aren’t going to be able to use it.

Further reading: Here is a link to my talk, my slides and my resources.

Is GraphQL really “self-documenting”?

If you Google for ‘API trends’ or ‘the future of APIs’ , one technology that crops up a lot is GraphQL. Developers rave about it being a more powerful and flexible alternative to REST. Not only that but if you’re a technical writer like me, claims that it is self-documenting are particularly interesting. So what is GraphQL and is it really as self-documenting as people say?

What is GraphQL?

GraphQL is an open source data query and manipulation language that was developed internally by Facebook for their mobile applications before being released publicly in 2015. Since then it has grown in popularity with some people claiming it might replace REST APIs in the future.

Like REST APIs, both operate over HTTP with requests being sent to retrieve or manipulate data. The key difference is with REST you might need to send requests to multiple endpoints to retrieve a particular set of data, with GraphQL there is only one endpoint so with a single request you can retrieve an object and all of its related objects.

For example, with this GraphQL schema and server wrapping the SWAPI (Star Wars API), you can retrieve multiple pieces of data using just one endpoint. In this case, finding out the species and home planet of Luke Skywalker by adding more fields to the endpoint:

Star-Wars-GraphQL

“The self-descriptive nature of GraphQL”

There seems to be plenty of love for GraphQL on Twitter with developers praising its speed, flexibility and introspective nature. The other key attribute that crops up a lot is “self-documenting” or “self-descriptive”:

One developer even went as far to say that GraphQL doesn’t require documentation at all. However, after playing around with GraphQL and experimenting with some public GraphQL examples out there, I’m not so sure I agree.

Naming matters

The key thing about GraphQL from a documentation perspective is the importance of naming. Lee Byron, one of developers behind GraphQL, spoke about this in his talk “Lessons from Four Years of GraphQL” at the GraphQL Summit in November 2016: “Naming things is super important in GraphQL APIs,” he said. “An important question to ask when designing APIs is ‘Would a new engineer understand this?'[… ] And that means no code names or server-side lingo.”

Lee-Byron
Lee Byron, one of the developers behind GraphQL, spoke about the importance of naming.

He continued: “Imagine that most of the engineers who are going to be using your API might not find it so easy to go and find out how that field maps to some underlying system. It’s really important not just to have names that are good but to have names that are self-documenting. Naming things that adhere closely to what those things actually do is really important to make this experience actually work.”

“An important question to ask when designing APIs is ‘Would a new engineer understand this?’ […] Naming things that adhere closely to what those things actually do is really important to make this experience actually work.” – Lee Byron

Despite Byron’s warnings, fields with poor or no descriptions were a common issue in the different GraphQL APIs I looked at. In the example below, taken from the GraphiQL documentation explorer, I had no idea what the ‘section’ query field did or what data it sent back because it had no description:

Screen Shot 2018-07-25 at 18.44.37

Apart from the documentation explorer, another way to see what query and mutation fields are available is the auto-populating feature in GraphiQL. Hovering over the field or type reveals a description but this can be as useless as the description in the documentation explorer if all it says is ‘Self descriptive’, as this Twitter user found out:

Does GraphQL need documentation?

I agree that GraphQL is self-descriptive and if you’re familiar with the query language and the schema, its introspective nature means it is easy to refer to the description of a field or type to find out what it does. One of the other advantages of GraphQL is the API documentation is easy to keep accurate and up-to-date as the descriptions are pulled directly from the code. In version 0.7 or above of GraphQL, this is as simple as adding a comments directly above the type or field in the code:

Star-Wars

However, GraphQL is only “self-documenting” if the developer or a technical writer has given the fields adequately intuitive or self-descriptive names or has added decent descriptions for them in the schema code. If the names are obscure or the descriptions aren’t great then your GraphQL API is as useful as a chocolate teapot and there are already a few chocolate teapots out there from what I’ve seen. So I guess the good news for technical writers is that we still have a role to play in helping to document GraphQL, it isn’t a magical solution that renders us unnecessary just yet!

👽 The Emoji Invasion

A critic labelled the ‘text speak’ of the 1990s as “penmanship for the illiterates” but the latest threat to written English is the emoji, said to be the fastest growing language in the UK. While ‘text speak’ saw words shortened and abbreviated, emojis have replaced text altogether, harking back to the dark ages of cavemen and hieroglyphics, when pictures formed the basis of communication.

The rapid spread of emojis into modern communication has seen a translation company hiring the world’s first emoji translator, a restaurant launched in London with an emoji menu and the recent release of the Emoji Movie in our cinemas. So, where did they come from and is there a place for them in modern communication and technical writing?

🎬 Origins of the Emoji

The emoji first appeared on mobile phones in Japan during the late 1990s to support users’ obsession with images. Shigetaka Kurita, who was working for NTT DoCoMo (the largest mobile-phone operator in Japan), felt digital communication robbed people of the ability to communicate emotion. His answer was the emoji – which comes from the Japanese ‘e’ (絵) meaning “picture” and ‘moji’ (文字) “character”.

2000
One of the original set of 176 emojis designed by Shigetaka Kurita

The original emojis were black and white, confined to 12 x 12 pixels without much variation. These were based on marks used in weather forecasts and kanji characters, the logographic Chinese characters used in Japanese written language. The first colour emojis appeared in 1999and other mobile carriers started to design their own versions, introducing the smiling yellow faces that we see today.

aa-Cover-4fu6auljfsrl2jr5qirr1deh76-20161217051451.Medi
Shigetawa Kurita, the 👨‍👩‍👧 father of emojis, felt digital communication robbed people of emotion.

Speaking to the Guardian, Kurita admitted he was surprised at the popularity of emojis. “I didn’t assume that emoji would spread and become so popular internationally,” he said. “I’m surprised at how widespread they have become. Then again, they are universal, so they are useful communication tools that transcend language.”

“I’m surprised at how widespread they have become. Then again, they are universal, so they are useful communication tools that transcend language” – Shigetaka Kurita.

However, Kurita doesn’t believe emojis will threaten the written word. “I don’t accept that the use of emoji is a sign that people are losing the ability to communicate with words, or that they have a limited vocabulary,” he said. “Some people said the same about anime and manga, but those fears were never realised (…) Emoji have grown because they meet a need among mobile phone users. I accept that it’s difficult to use emoji to express complicated or nuanced feelings, but they are great for getting the general message across.”

💹 Emojis in Marketing

It is this ability to get the message across very simply that has resulted in companies using emojis more and more in marketing, particularly on platforms like Twitter and via email. It has become a way for brands to humanise themselves, have a sense of humour or put across a message that a younger audience can relate to.

One example of emoji marketing is a Tweet sent by Budweiser which was composed entirely of emojis to celebrate the 4th July this year:

Meanwhile, Twentieth Century Fox took emoji-based humour to whole new level with posters and billboards bearing two emojis and a letter (💀💩L) to announce the release of Deadpool in 2016:

Deadpool.png

✍️ Emojis in Technical Writing

A number of tech companies, especially those with a younger (in their 20s-40s) target audience like Slack and Emoji, have also embraced the use of emojis in their technical documentation and the software itself.

Slack3.png

Slack use them sporadically in the product, often as the punchline of a joke or message when you’ve read all unread threads (see screenshot above).

Emojis also appear in their help system, with Emoji flags for the chosen language and to highlight bullet points (see below):

Slack-emoji2

Startup bank Monzo also embraced emojis early on, designing an emoji-rich interface that would a younger client base than typical banks could relate to. Emojis are automatically assigned to transactions and you’ll find them incorporated in the Monzo API documentation and the app’s Help screen:

Monzo-mojis

iPhone6---Front-Black---by-JustD

Speaking to brand consultants Wolf Olins, CEO Tom Blomfield explained how they also use machine learning to pair your transaction’s spending category with relevant emoji. For example, it will display the doughnut emoji 🍩 when you shop at Dunkin Donuts. He said: “There’s no business case for the emoji donut, but people get ecstatically happy when seeing it and go on social media to share the moment.”

☠️ Risks of using Emojis

While emojis might work for some tech companies and give them a way to humanise their brand and relate to their target audience. I think there are several risks which come with their use as well.

The first risk is alienating users who don’t relate to emojis, or even dislike them. Although most of my office do use them as a way to react to each others’ Slack posts etc, there are a number of people who refuse and as there are a lot of nationalities with different cultural references, sometimes the emojis are used in different ways. For example, in Japan the poop emoji (💩) is used for luck while the English use is a lot more literal. Similarly, the folded hands emoji (🙏) means ‘thank you’ in Japan, while it is more commonly used to convey praying or saying ‘please’ in English usage.

Secondly, if emojis are just a fad like the Kardashians, Pokémon GO and Tamagotchi then you face the unpleasant task of replacing them all when they become unpopular, are considering annoying or are phased out. If you have saturated both your product and documentation with emojis then this task will take you and your team a lot of time and effort.

Thirdly and finally, studies have shown that emojis can get lost in translation as they are incredibly subjective so the meaning and intended emotive message can often be misinterpreted. This has continued to get more and more muddled as different vendors and browsers redesign and create their own versions of the unicode emoji characters. A study by GroupLens research lab found evidence of misinterpretation from emoji-based communication, often stemming from emojis appearing differently on different platforms.

Screen_Shot_2016-04-11_at_8.49.09_AM

The grimace emoji (😬) is said to cause the most confusion, with researchers finding that 70% of people believed it to be a negative reaction while 30% thought it conveyed a position emotion.

On the whole I don’t dislike emojis or think they’re a threat to the written word. They definitely have a role to play in social interaction, can humanise communication and even add humour to it. However, I still feel there are too many risks, too many different cultural interpretations which mean they simply won’t work in a multinational business. Technical writing is all about choosing the clearest form of communication, the shortest, most simple words that cannot be misunderstood. I’m just not convinced there’s a place for emojis in documentation yet, at least not while there is still room for things to get lost in translation.

Debugging the word ‘Bug’

Etymology and the origin of English language have always fascinated me, partly because so many of the words we use every day represent remnants of history; artefacts left behind by the Roman Empire, the Vikings and the Norman conquest. Although words relating to computing and technology are much younger, some are just as quirky and steeped in history as those from the past.

Like a Moth to a Flame

The origin of the word ‘bug’ in the computing world is often mistakenly credited to computer scientist Grace Hopper. The story goes that while working on the Harvard Mark II computer in 1947 she discovered a dead moth stuck in a relay. It was removed and taped into a logbook where she wrote “First actual case of a bug being found” (see picture below), which suggests that the term was already in use at that time.

H96566k

While this might have been the first literal case of ‘debugging’, there is evidence that ‘bug’ had been used in engineering for many years before that.

Scarecrows, Bugs and Bogeys

The most accepted origin of ‘bug’ is the Middle English word ‘bugge’ or ‘bogge’ (n.), which meant a scarecrow or a scary thing. One of the first iterations of the word came in John Wycliffe’s English translation of the bible (circa 1320-1382): “As a bugge either a man of raggis in a place where gourdis wexen kepith no thing, so ben her goddis of tree.” (As a scarecrow or a man of rags in a place where gourds grow guards nothing, so are their gods of wood.)

Bugs-2.png
‘Bugge’ (n) originally meant scarecrow then became an early name for bedbug.

As language evolved, another off-shoot of ‘bugge’, the scarecrow, was ‘bogey’, an evil or mischievous spirit. This gave rise to a family of other ghost and hobgoblin names including ‘bogeyman’, ‘boggart’, ‘bogle’ and ‘bugaboo’. While the archaic form of ‘bugbear’ is also another hobgoblin figure. In general these all have the same negative connotation of things to avoid and that cause fear or irritation. The direct descendant of these words is ‘bogey’ which still survives today in modern English, in aviation where a ‘bogey’ is an enemy aircraft, in golf where a ‘bogey’ is one over par (a bad score) and a ‘bogey’ (UK) or ‘booger’ (US) is a piece of nasal mucus.

giphy (1).gif

By the middle of the seventeenth century, the word ‘bug’ no longer meant scarecrow and had come to mean ‘insect’, which makes sense as many people consider them to be alien and scary. The earliest references to ‘bugs’ meaning insects often related to ‘bedbugs’, supposedly because when someone woke up covered in bedbug bites, it was as if they had been visited by something scary during the night.

Thomas Edison’s Bugs

By the 1870s, the meaning of bug had changed once more and perhaps made its first appearance in technology when American inventor Thomas Edison referred to what he called a ‘bug’ while developing a quadruplex telegraph system in 1873. He also mentioned ‘bugs’ in a letter to an associate:

“It has been just so in all of my inventions. The first step is an intuition, and comes with a burst, then difficulties arise — this thing gives out and [it is] then that “bugs” — as such little faults and difficulties are called — show themselves and months of intense watching, study and labor are requisite before commercial success or failure is certainly reached.”

They were mentioned once again in an article in the Pall Mall Gazette in 1889:

“Mr. Edison, I was informed, had been up the two previous nights discovering ‘a bug’ in his phonograph – an expression for solving a difficulty, and implying that some imaginary insect has secreted itself inside and is causing all the trouble.”

Another early example of ‘bugs’ being used to refer to technology was with the release of the first mechanical pinball machine, Baffle Ball, which was created by David Gottlieb in 1931. It was advertised with the strap-line “No bugs in this game!” (see poster below):

No-Bugs1
So it seems fair to assume that the word ‘bug’ came from ‘bugge’, the Middle English for scarecrow, which led to ‘bogey’ and all the similar words meaning an obstacle, a source of dread or something to be feared. In modern times the word ‘bug’ has become a verb meaning to vex or irritate, while the noun form has become a synonym for disease-causing germs, crazily enthusiastic or obsessive people (e.g. a firebug is a pyromaniac), concealed recording devices used by spies and perhaps, thanks to Edison, an error in technology.

 

 

 

Snapchat’s UX: A Confusing Mess?

Snapchat might be the image messaging app of choice for today’s teenagers, with 10 billion daily users, but in my opinion the UX and interface design is a confusing mess and others seems to agree (‘Why is Snapchat’s UI so bad?’, ‘The Generation Gap of Snapchat’, and ‘Snapchat Built to Be Bad‘ are just some of the top hits when you search “Snapchat UX” in Google).

It’s frustrating but even as a fairly technical 31-year-old who has mastered the likes of WordPress and Twitter, I don’t think I’ve ever found  an app that is so un-intuitive. It seems the only way to learn how it works are by reading the various on-board prompts or through trial and error.

iphone-160307_960_7201

Take the home screen for example, my biggest issue for new users is that the majority of the icons are not universal. I’ve circled the icons I believe are fairly universal in green and highlighted uncommon/unknown icons in red:

iphone-160307_960_720

So of the seven icons/functions, only three (camera rotation, messages and take a photo) are obvious, the others are all ambiguous. Snapchat actually tells me that the ghost icon is where my contacts and settings ‘live’ through a bit of on-boarding but as for the small circle at the bottom and the dots in the bottom right, I’d have no idea unless I clicked them. Even the ‘flash’ icon in the top right isn’t the standard lightning bolt flash that you would expect to see on most cameras. Why make it ambiguous? It seems totally illogical but is it intentional?

The "stories" screen gave me a headache but that's another story...
The “stories” screen gave me a headache but that’s another story…

There are several theories to why it has been so successful despite having this seemingly un-user friendly design. One theory is the bad UX is intentional. By making it difficult for new or older users, its difficult for parents to look up posts by their children and their teenage friends without knowing their screen name. As a result posts remain personal. This theory was in part confirmed by CEO Evan Spiegel: “We’ve made it very hard for parents to embarrass their children. It’s much more for sharing personal moments than it is about this public display.” Similarly Amin Todai from Canadian creative design agency One Method wrote a blog post likening it to creating a new language that only under 30s could hear: “By virtue of it having an incomprehensible user interface, Snapchat has essentially created a new language that only people under the age of thirty can hear. Like a dog whistle for teens, except with more pictures of dicks and boobs.”

“Snapchat has essentially created a new language that only people under the age of thirty can hear. Like a dog whistle for teens, except with more pictures of dicks and boobs” – Admin Todai

That last comment brings me to the other reason that teenagers and others have flocked to Snapchat despite the poor UX/UI: dicks and boobs – the pornography aspect. It became an instant guarantee of seeing up to 10 seconds of nudity, whether it be horny teenagers wanting to see their love interests naked or glamour models sharing their goods, ultimately sex sells and Snapchat was offering it up , whether intentionally or not, to millions for free. In the same way that pornography is addictive, so is celebrity and there are a huge number of celebrities on the site, all offering instant snippets of their lives for all to see. The Kardashians, the Jenners, Justin Bieber, the Jonas brothers, are just some of the celebrity users who appeal to the teenage  and young adult Snapchat audience.

biebs.jpg
Snapchat users like Justin Bieber attract a younger audience.

The other theory is that Snapchat is basically more about fun than function and that is what gets people using it. Irrespective of how awful the UX is, youngsters will keep coming back because they find it fun to use, to share moments and stories, and to mess about with the different effects, filters and lenses to make funny photos and videos. Ultimately, I think all three of these theories have had some part to play in Snapchat’s success and there is clearly a generation gap in play here but maybe that’s the point, its popularity is down to it not being popular with my generation because we were never its target audience, it was always intended to be more fun for the younger generation it resonates with.

The Origin of the Hamburger and Other Icons

The emergence of the three-lined “Hamburger” menu icon in modern interface design was so fast I had just assumed it was a relatively new creation. However, after a bit of research I discovered its origins were far more rooted in the history of technology than I first thought. It was software designer Geoff Alday who made the discovery, which he wrote about in this blog post, learning that icon was first used back in the early 1980s on the interface of the Xerox Star work-machine, one of the grandfathers of the modern personal computer. You can see it shown in the middle of the screenshot from 1981 below:

2016-07-07 16_19_22-Start
A bit-mapped screenshot from the Xerox Star workstation released in 1981.

Norman Cox, the designer behind the icon, said its design was meant to be “road sign” simple, functionally memorable, and mimic the look of the resulting displayed menu list. Cox later told the BBC it was jokingly referred to as the “air vent” icon. He said: “At Xerox we used to joke with our initial users that it was an ‘air vent to keep the window cool’. This usually got a chuckle, and made the symbol more memorable and friendly.”

“At Xerox we used to joke with our initial users that it was an ‘air vent to keep the window cool’. This usually got a chuckle, and made the symbol more memorable and friendly” – Norm Cox, former Xerox designer

The icon didn’t really appear for nearly 30 years until it was adopted as a menu icon by social networking site Path, which launched in 2010, and then later Facebook and Apple iOS applications, meeting a growing need for more content to fit onto smaller smartphone screens via the use of menus. It has since become widely-accepted as a menu icon by UI designers and can found everywhere from web browsers Google Chrome and Mozilla Firefox, to news websites such as the BBC and others.

2016-07-08 13_46_49-Photos-firefox

2016-07-08 13_47_24-Chrome

2016-07-08 13_51_08-Home - BBC News

2016-07-15 14_53_20-News, sport and opinion from the Guardian's UK edition _ The Guardian

After some more research I soon discovered that there were a number of other prominent icons and symbols still used today that first emerged in the 1980s. Apart from the ‘Hamburger’ icon, Norman Cox is also attributed with creating the document icon, which was another part of the Xerox Star interface. This image here shows the design development. After Cox, one of the most prolific designers of the 1980s was Susan Kare who worked for Apple Macintosh. Descendants of her early designs that still exist today include icons such as the lasso, the grabber, and the paint bucket. You can see some other the examples of her work in the screenshot below:

02_macicons
A selection of designs by Apple Macintosh designer Susan Kare.

She also came up with the command key design (⌘) that still appears today on most Apple keyboards. Kare apparently discovered it while browsing through a symbol dictionary and found it was commonly used on signposts in Scandinavian countries to mark places of interest. When asked by MacFormat magazine about the longevity of her icons she said: “I am very grateful and appreciative that some images I designed almost 30 years ago are still in use. I believe that symbols that are simple – not too many extraneous details – and meaningful can have a long life span.”

Other icons that have survived since the 1980s are shown in the table below:

  Icon  Name  Designer/Creator
menu-alt-512 Hamburger icon Norm Cox for Xerox Star.
ios7-document-icon Document icon Norm Cox for Xerox Star.
command-symbol_318-74882 Command icon Susan Kare for Apple Macintosh.
Susan-Kare-fill-icon-660x660 Fill icon Susan Kare for Apple Macintosh.
mouse-cursor-icon Mouse icon* Douglas Englebart for Xerox PARC
common-search-lookup-glyph-128 Search icon  Keith Ohlfs for NeXT Inc.

*The mouse cursor arrow originally pointed upwards but because resolution was so low it was easier to draw an arrow at a 45 degree angle.

10 Tips for making Content more Engaging

I’ve always liked to learn new bits of software by trial and error, trying things out for myself first and learning from my mistakes but there’s only so far you can get before you get stuck. This is why documentation and help are so invaluable because a piece of software is worthless unless you know how it works.

1c00898.jpg

In today’s fast-paced world, people don’t have time to read chunky 900 to 1000 page manuals, they want information to be quick and accessible. As a result, technology companies and their technical writers are having to adapt their techniques and content strategies to make documentation more exciting and engaging for readers.

Here are some of the best ways to keep people interested in your content:

1. Pictures

As you have probably seen from my blogs, I am a real advocate for using good images to break up text and make documentation more approachable and more visually interesting.

2016-05-20 11_32_36-Mozilla Support.jpg

This is just the Firefox help homepage but as I mention in my blog last week, I thought the design and use of imagery was really visually appealing.

2. Videos

Taking this approach one step further, videos are another brilliant and effective way to engage help users as long as they are well put together, short and succinct.

The example above is one of Skype’s excellent video tutorials which are really well produced.

Videos can be made with software such as Camtasia or free tools such as Open Broadcaster Software.

3. Gifs

Like videos, it is possible to add gifs to make your content more dynamic and visually interesting. They are a quick simple way to show an example of how something is done:

Animation

This gif was produced using free open-source software called ScreenToGif.

4. Infographics

I think graphics are a great way to get a lot of information across to your readers in one image if they are designed well.

all-about-spotify-and-ecosport_527a5b85c6af0_w1500

The Spotify infographic above has 10 separate facts spread across one image.

5. Examples

Using examples is the best way to show your readers what you are trying to explain.

2016-06-02 14_05_27-Embedding a Tweet on your website or blog _ Twitter Help Center

On the page above, taken from the Twitter, the help describes how to embed a Tweet and then gives examples.

6. Be Human

Use an informal or conversational writing style. Write as if you were describing how the software works to a friend. Readers won’t engage with a robotic tone of voice.

2016-06-02 14_07_29-People You May Know _ LinkedIn Help

Linkedin’s Help addresses users by their first name to make the experience more personal.

7. Keep it Short

Don’t overwrite. If you can explain it in one sentence then write one sentence. It’s better to use 25 words rather than 250. The shorter the better.

2016-06-02 14_10_12-Login Basics _ Facebook Help Centre

Facebook’s Help Centre covers the login basics in just 73 words (and three links).

8. Keep it Simple

Don’t use lengthy words the average person won’t understand or that will get lost in translation. Go with “move in a circle” rather than “circumbilivagination” or “use” instead of “utilise”.

2016-06-02 14_14_05-Start

Sorry Royal Mail but I really dislike the use of “utilise”, it’s just a waste of four letters!

9. Easy Navigation

If your help system is easy to work your way around then people will want to use it.

2016-06-02 14_20_59-Start

Skype’s Help is really easy to navigate from my experience. You can check it out here.

10. Make it fun!

Use humour and unusual text to catch people’s attention. This is discussed by Mozilla’s Michael Verdi in his presentation How To Write Awesome Documentation.

Atlassian Confluence’s help system, shown below, encourages new users to join a fictional space program and complete a mission:

2016-06-01 14_40_40-Get started - Atlassian Documentation

2016-06-01 14_40_57-Tutorial_ Navigate Confluence - Atlassian Documentation

Sure, it’s a bit wacky and off-the-wall but its fun, it catches attention and keeps readers interested and engaged.

Help Review – Twitter

My stepmum recently asked for help publicising something online and my first suggestion was Twitter but explaining how to use it was a challenge in itself. Although it’s been around for a decade, I still don’t think it is that intuitive for someone who is unfamiliar with the basic concepts and terminology. As a result, the help is vital in explaining how to use it, what Tweets and Retweets are and the importance of followers.

https://twitter.com/willwillynash/status/729717349771816960

Twitter’s Help link can be found by left-clicking your profile picture and scrolling down to the word Help or by clicking Help in the bottom dashboard.

Twitter2.jpg

First Impressions

The help homepage is pretty stylish, with a prominent white search panel where users can search for what they’re looking for. Underneath there are six key headings for commonly asked questions and even further down there are further sub-headings, a video tutorial and trending topics. Right at the bottom of the page there is an footer with some Quentin Blake-style cartoon people, presumably a hapless user and some friendly Twitter support staff in their Twitter-Blue uniforms. All very quaint but slightly disjointed if you compare the style of the trendy header with the children’s book illustrations in the footer.

Twitter3.jpg

Just testing it out as a “new” user to get to grips with the basics, there is the ‘Using Twitter’ section which introduces to the general concepts and there is a useful ‘Getting started with Twitter’ page, along with a glossary which even experienced users might find useful.

Features

The Twitter Support account is a great little feature. By creating a support account in their own social networking service, it not only encourages user engagement but the process turning to help becomes a seamless part of the Twitter user experience. It’s very neat.

2016-05-10 21_38_51-Twitter Support (@Support) _ Twitter

Commonly asked questions were mostly account-related, either being locked out or wanting to deactivate an account. For more complex issues that require assistance or intervention, the Twitter staff ask users to log a support case, referring them to this page here.

2016-05-11 11_20_04-Request help signing in to your account. _ Twitter Help Center

There is a nice and simple video tutorial about how to mute or block users featuring the same Quentin Blake cartoons. It is nicely put together but I think it’s a shame there aren’t more of these, like a bank of different tutorial videos. The only example I could find on the help site was how to mute a person on Twitter (I’m guessing this was the most commonly asked question the support team were asked):

I checked Twitter’s YouTube channel and there is a slightly longer version of this video, detailing how to block and report users but that was all. I think they’ve missed a trick here but I guess any answered questions can be Tweeted to their support account.

Hidden Features

It’s not so much a hidden feature but something I didn’t know about are the Twitter keyboard shortcuts. This list can be accessed by clicking on your profile picture and clicking Keyboard Shortcuts on the menu.

2016-05-10 22_04_21-Cortana

Another neat trick is the ability to embed Tweets. This can be done by either clicking the   ••• More (ellipsis) icon and selecting Copy Link to Tweet or Embed Tweet.

It’s quite a nice way to enhance content on a webpage. News sites in particular use this feature as a way to embed quotes from people, normally famous people or politicians, who have written something newsworthy on Twitter.

Conclusion

While it has some cool features, I would have thought Twitter could have added some more innovative aspects to their help, videos or maybe Vines in particular. I think the Twitter Support account is a good idea and it’s clearly being used quite actively. However, this could also be an indication that not enough people are using the help. Additional videos on recovering passwords, unblocking an account and deactivating accounts and sharing them on their Support account would probably halve the number of Tweets they receive. Despite this, I did like the style of the documentation itself, the familiar cartoon illustrations make it approachable and the content itself is a happy medium between informal and informative.