The aim of this blog is to introduce the work I do – and to lay some basic standards that must be used by the developers whenever they are playing with language, or grammar. This blog also has some content that has been picked up while reading the works of other Writers, and I would like to thank them for sharing and increasing my knowledge.

A Technical Writer (TW) – that’s who I am.
And no, I am not a robot built on some new technology who can write. I am someone who writes about technologies and products in a way that even a layman can understand their intricacies and functioning.

The unofficial part is what makes my life interesting – and a whole lot challenging. This part involves dealing with developers – people who are going to give me the info I need to write my guides. Apart from playing with the products so that I can understand them – and thereby write – better, there are certain things that need to be discussed with the developers who write the code and understand the technology.

Error Messages: Just let them be small speed breakers – not roadblocks

While playing with a product, I need to click a lot of buttons, work with the menu options provided, and – oh woe is me! – view the sometimes confusing, sometimes horrifying error messages.

An error message I once encountered read “something has gone wrong somewhere”. The utter shock and the feeling of despair attached to the message did not even let me react to it for a few moments. When I came to my senses, I had no option but to draw my pen (mightier than the sword) – and slash open the responsible developers’ mind to fill it with a dose of some common grammar and ethical knowledge.

Error messages are supposed to soften the impact of ‘something that has gone wrong’ – they themselves must not add to the confusion. An effective error message must be able to guide the user to the proper action to be taken – if your UI design fails to do so. If your error messages are clear and concise, not only will they help the user move around the product with ease, but you will also be able to retain their interest and attention – thereby building loyalty.

Some standards to keep in mind while writing an error message are:

What Questions must the Error Message answer?
An error message should answer three questions, in this order:
1. What’s the problem?
2. How do I fix the problem?
3. How do I avoid the problem in the future?

The answer to these three questions is enough information to inform and encourage the user to complete the task. It also subtly ensures users that they are dealing with a competent, trustworthy product.

What must be the tone and voice of my error messages?
You may lose the user if the voice of an error message is not pleasing. The user has done something that has resulted in a bug, which displays the error message. Now, if your language is also not friendly, the user may choose to stop using your product.
The error message must sound like an advice from a patient friend – not make the user feel like a patient being treated by an irritable doctor. A few do’s and don’ts regarding the error message voice are provided below:

Do

  • Make your tone warm and personal by using personal pronouns as “you” and “your.”
  • Take the responsibility of the error – do not blame the user.

Don’t

  • Do not use language that makes users feel that they are being shouted at. Shouting may be perceived when an error message contains exclamation points, long strings of capital letters, and bright red or yellow icons such as stop signs or yield signs.
  • Do not use urgent or excited terminology such as “fatal,” “critical,” “severe,” “failed,” or “terminate.” Calm language is more likely to produce a calm reaction.
  • Do not use techie jargon, code, or abbreviations. Humans are reading the error message, so use language a human will understand.

Where must I place the message, and in what format?
The error message must not be such that it makes the users waste their time by forcing them to investigate what went wrong. The placement must be pleasant, and at a place where the users may not have to strain their eyes. The most effective placement of an error message is within a JavaScript pop-up, which the user must acknowledge and close before it’s possible to proceed. You are probably familiar with the standard gray JavaScript boxes that pop up in the middle of your screen any time you make a potentially erroneous decision.

For maximum readability, stick with basic sans-serif fonts in dark, basic colors (such as black), and use a 10-point (or larger) font size.

Must the Length of an error message be fixed?
The length of an error message is not so important as the message being concise and to the point. Limiting the length of an error message should not be your first priority.

Colons in the field names
The correct use of colons is something I have tried to propagate since I started to write, – and sadly, still have to continue doing the same. As per the rules, in English-language, no space is placed before a colon and a single space is placed after it.

For example, ‘Star Wars Episode IV: A New Hope’.

With the above example, I fervently Hope that all developers, whenever they are labeling fields on the UI, will stop using something like Name : ___‘ – and Start Using ‘Name: __’.

Consistency of Button Names

Most of times, a big project is divided into smaller modules, each of which is handled by different developers. Though the management of the project becomes easier, the language consistency goes for a toss due to the inclination and style preferred by the different developers.

For example, one may feel that using OK/Cancel combination is correct, while another may feel at ease using Yes/No.

This inconsistency in naming the buttons (a Yes/No combination on one screen – and an OK/Cancel on the next) – if not corrected in time, may become an irritating experience to the new user. The only way out, I feel, is to set up certain standards and practices about the usage of these names, and then make the developers stick to these rules.

The Ellipsical Orbit
Another commonly (mis)used element of grammar that I have come across on various screens and error messages is the Ellipse (…).

Ellipses are a series of dots used to indicate the omission of words or paragraphs from quoted material.

Basically, from the UI perspective, the places I have seen ellipses being used are with the ‘Browse…’ option, or to indicate that some more options are provided in a certain sub-menu option.

Do not use more than three dots ‘…’ in such cases.