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:

Oxymoron

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! 🙂

Advertisements

Technical Writing versus Creative Writing

When some of my non-IT acquaintances come to know that I work as a Technical Writer, their question goes like, “What do you write?”. Indeed a good question. I write user manuals, employee orientation manuals, step-by-step procedures of setting up or troubleshooting some system, and the things alike. Their next question follows, “Oh, then don’t you write stories?” All I can say is, may be they didn’t pay attention to the word technical.

Since our conversation involved technical writing as well as a reference to creative writing, I try to throw light on these two writing styles.

technical-versus-creative-writing-med

Technical writing and creative writing both are audience oriented writing styles, which require writing talent as well as critical thinking. Yet, how are these two styles are different from each other? Let us know about them one by one.

What is Technical Writing?

Technical writing is the manner of simplifying and presenting any complex information in such a way that it is understandable and usable by the people who need it. The people for whom this information is presented are called target audience. The objective of Technical writing is to inform the target audience about facts or to instruct them on how to set-up or fix something.

It almost always uses formal tone of language. That means a technical writer uses Dear Sir in place of Hi Dude, contact instead of get in touch with, and inform in place of tell. 🙂 It is not just about using formal and precise words. It comes with a set of rules regarding grammar, language, formatting, and presentation.

Technical writing can be either online or offline. It refers styling guide, specialized vocabulary, and narrates things quite straight forward.

Examples of Documents Prepared by Technical Writers

System Reference Manuals, User Manuals, Product Specification Documents, Troubleshooting Guides, Reports, White Papers, Online or Offline Help, and Case Studies are few important examples of the documents prepared by technical writers.

Who Uses the Documents Prepared by Technical Writers?

A large number of professionals and general users refer to the documents prepared by technical writers. For example, engineers refer design specifications for some mechanical, electrical, or electronic component. Software testing professionals use test plans for code testing. System operators refer to instruction manuals. Marketing professionals use reports for planning their marketing campaigns. Management team of a business refers reports and white papers for major decision-making. Software application users request help on the software which they can induce by pressing F1 key. Last but not least, general audience refers to the user manuals to know how to use or set-up their newly purchased device.

What Does it Take to Become a Technical Writer?

To become a technical writer one needs to have related education, skills, knowledge of document types and the rules for creating reliable documents. One needs to have flair for writing and a sound understanding of three vital things: subject, objective, and the target audience. It is also required to understand the system thoroughly to be able to provide any information or instructions to its potential users.

Command over working language, knowledge of any foreign language(s) other than English, graphics tools, and image processing applications, handling Content Management System (CMS), knowledge of editing a website are some vital requirements to become a proficient technical writer.

How is it Like Being a Technical Writer?

As a technical writer I develop the documents that go through the Document Development Life Cycle (DDLC), which is similar to any product development life cycle. There is a lot of unorganized information to handle in the form of numbers, technical terms, definitions, procedures, charts, and all factual data. My work involves interacting with Subject Matter Experts (SME) for important inputs regarding the subject. It also includes dealing with graphic designers for images and infographics, or creating them myself. At times I need to handle various types of media such as audio and video.

I conduct self-review on my own work, as well as ask my colleagues to conduct a peer-review from the perspective of a new reader or an examiner. Reviewing enables to figure out and remove any loopholes in the written work. Finally, I compile and present the information in such a way that the users can access it quickly.

While being in the shoes of a technical writer, I may or may not be working on a technical subject, but I work on a subject technically.

The 7 C’s of Technical Writing

Technical writers develop their documents by adhering to the following seven rules or rather, guidelines:

Clarity

Leaving no confusion for the readers. Removing ambiguities and doubts.

Correctness

Removing grammar mistakes, factual errors, or typo errors before the readers reveal them. Presenting accurate information always.

Concision

Using brief and precise words. Replacing lengthy phrases with single words without losing essence of the subject.

Consistency

Using uniform terminology and style of formatting throughout the document or across multiple inter-related documents.

Coherence

Organizing and connecting the pieces of information seamlessly. Afterall, it should make sense to the target audience.

Completeness

Providing all required information within the predetermined scope.

Credibility

Working professionally to provide high quality content.

The beauty of technical writing lies in simplifying information for the consumption of others. Technical writing develops a person to be very meticulous and makes not to settle for anything less as far as the quality and presentation are concerned. 🙂

Now let us see,

What is Creative Writing?

It is a style of writing about a subject creatively so that the reader or listener indulges in to it. The objective of creative writing is either to entertain or to educate the audience.

Creative writing uses prose with informal or casual tone. This style of writing is not governed by any set of strict rules regarding grammar or language. The writer has ample freedom of imagination and narration. Creative writing involves use of artistic phrases, poetic devices, and story writing elements, which themselves are the topics of great length.

It is accessed by general audience because people of any age can read books, go through poems, or watch plays and movies with great scripts. Creative writing uses general vocabulary and is descriptive. Unlike technical writing, it can involve use of slang if the situation or culture being portrayed, or characterization demands.

Examples of Creative Writing

Diary, Poems, Plays, Shayari, Stories, Fictions, Autobiographies, Novels, Essays, Comic Strips, and Scripts and Dialogues of movies are some examples of creative writing.

What Does it Take to Become a Creative Writer?

To become a creative writer, one needs a great deal of observation, knowledge of the subject, and writing talent to put everything together into words. One needs to generate engaging content, which compels readers to attend uninterruptedly. A good grip over language, employing one’s creative abilities and leveraging the power of words to influence and modify emotions of readers, listeners, or viewers are some of the vital qualities a creative writer should possess.

A creative writer is capable of portraying a world through either own imagination or experience, and taking the audience on the trip to that world in their minds; sitting at a place.

Here is a brief comparison:

 

Writing Elements Technical Writing Creative Writing
Tone Formal Casual
Vocabulary Specific Generic
Audience Targeted General
Writer’s Viewpoint Objective Subjective
Place for Emotions Nil Ample
Information Organization Alphabetical, Chronological, Logical, or Thematic. Random

To conclude,

Technical writing and creative writing can be viewed as two portions of the same day a professional person spends. During the office hours, a professional person refers to what the technical writers produced for him and during his leisure time, he seeks for what the creative writers around the world prepared for him. 🙂