Writing Effective UI Text: Do’s and Don’ts

Software communicates with its users through User Interface (UI) text. Software developers anticipate what can go wrong and where, while coding. According to those anticipated situations, they raise errors or warnings, or display any intermediate informatory messages regarding progress or impediments. These messages are known as UI text in the field of Software Development.

UI Text Discussion

Technical Writers need to work together with the software developers and Product Managers for writing most effective UI messages. Here are some guidelines to write them.

Writing UI text: Do’s

  1. Write clear. Users should be able to comprehend the UI message easily. Put your best foot ahead to help users understand the developments in execution, or what went wrong in case of erroneous situation. State the issue in plain language with the concise use of words.
  2. Provide a supplementary message. It is written in continuation with the main error message when more details need to be conveyed during complex situation. The supplementary error message often helps users to understand why something went wrong.
  3. Write intuitive UI message. The message should give the users clue on what to do next and how they can restore the things to working order.
  4. Use small graphics with messages. A picture speaks thousand words. You can suggest the graphics designer to use relevant icons to depict the severity of unwelcomed situation. For example, a red-colored exclamation mark Error to indicate an error whereas an amber-colored exclamation mark Warning to indicate a warning. You can suggest some other graphic like Done to convey success.
  5. Watch out for your grammar. Keep a keen eye on contractions, well-placed punctuation marks, tense, spelling/typo mistakes, and so on. Correct grammar increases your software’s credibility.

For example, “The record has changed. Save it’s details?”. An incorrect contraction is used in the later sentence. It should be, “The record is changed. Save the record?”.

Writing UI text: Don’ts

  1. Don’t blame or order the user. For example, in the verge of using active voice, do not phrase an error message like: “You either did not connect router or you switched it off. Switch-on the router to be able to use Internet.”

Instead, say – “Router not found. Please make sure the router is connected and switched-on to be able to use Internet service.”.  The reliable policy is, inform about a situation in passive voice and suggest the action in active voice politely.

2.  Don’t leave any floating messages. There is a possibility of some unwanted messages getting displayed while executing. For example, see the one shown below:

Floating UI MessagesThe developer might have created some intermediate error messages for his/her convenience to test the status of certain device/situation while coding. If the developer misses out to remove such messages before creating a build, a Technical Writer can go through the file of error messages (if any) and help remove such floating messages.

3.  Neither use non-parliamentary words nor use jargon. Writing user-friendly doesn’t mean writing too casual that some users find hard to consume. Keep your organization’s brand culture in mind. Don’t phrase the UI messages using too casual tone with words like huff, hey, gotta, dude, or some non-parliamentary words. Also, avoid using jargon as non-technical users will find it difficult to understand.

For example, “Authentication failed.” is a jargon whereas “Incorrect password. Please enter the correct password.”, is user-friendly.

4.  Don’t confuse your users. Failing to anticipate the forthcoming situation clearly brings ambiguity in writing and in turn confusion in perceiving the UI message. There are some entertaining messages people have written. 😀 For example, see the message below:Confusing UI Message

What a frustrating message this is! 😀 Such messages do nothing to the users except for increasing their agony. 

Now see this, the oxymoron in the following message has made it quite humorous:


Ok, why would one write such message at first place? That was probably written by a developer who was testing the code snippet of killing a task forcefully.

An expert rightly says:

A user interface is like a joke. If you need to explain, it’s not that good.”

Appropriate UI text makes the software engaging in the right way, makes the software easy to use, and holds the brand image of the organization high in user’s mind. I trust you agree. Happy UI-text writing! 🙂