The Importance Of Interface Text (part 1)

Learn to create clear, usable and easily comprehensible text for your application's user interface.


A huge part of your application's success lies in how far it succeeds in making your users feel "I think I know what to do with this thing." And since you are, after all, developing an application around their needs, making sure the flow is built around a process they are already familiar with, it would be easy to assume that they would take to the application naturally.

Easy, but not correct.

Users approach any new tool with trepidation because it is, in essence, a whole new way of working. While you, as a developer, are looking at the application as a compilation of functions that they already know how to perform, the users look at it as a combination of screens that they know nothing about. The only thing that can bridge the gap between what they know and what they see is familiarity, and the easiest medium to make them familiar with the application is via the words they see on the application's user interface. Interface text, in other words.

Form Versus Function

While developing interface text would instinctively seem to be a very common sense affair, there is more to it than that. The biggest area of disconnect found in interfaces is that the terminology used indicates the technological function being performed by the application, whereas, when users come to the application, they're usually there for the purpose of performing a task and have little or no knowledge of the technology being used to implement the task. This lack of familiar terminology, added to the new dimension of an online interface, usually succeeds in throwing users off.

Let's take an example, a form that requires, say, a user to enter data about the hours of work logged in on various projects. Prior to becoming an electronic process, this task involved a timesheet log being delivered to the immediate supervisor, and the supervisor "approving" the log. The point of disconnect, once this simple process becomes electronic rather than manual, is the button on the supervisor's screen containing the term "validate" - which, though accurate, is jargon and not necessarily something the user is familiar with - instead of the term "approve" - which the user is familiar with.

This is one of the most common problems with user interfaces. A developer tries to make the interface indicative by reflecting accurately what the application is doing at a particular point. But the user never gains the benefit, since (s)he doesn't ever relate to, or understand, many of the terms the application sports.

Besides logical gaps between developer and audience, I have noticed a habit of approximating the terms used, leaving the task of figuring them out to the user, who would "anyway know what to do here". This may seem harmless enough at first, but can often cause serious delays at the user's end.

Let's take another example, this one from a real project I was recently developing documentation for. In a form requiring the user to set the frequency for a particular function, the fields provided looked like this:

The confusion here should be obvious: if the frequency can be chosen as "daily", "weekly" or "monthly", what is the second field for? Or, if the interface allows the user (as it seems to) to define the function to take place "5 times weekly", shouldn't it also allow the user to specify the time at which each execution should take place?

To an end user, a little more clarity here could mean the difference between a utilized hour and a wasted one. And let's not forget the nagging feeling the user now begins to have that maybe, just maybe, the application is not all that reliable after all...

Having set the tone, and hopefully, the necessity for this piece, let's get the ball rolling. Over the next few pages, I will attempt to lay down some ground rules to help develop simple and indicative interface text.

The First Date

In a software application, just like for code, there are front-end and back-end documentation requirements. Note that when I use the term "documentation", I am referring to all text-based inputs into the application.

The back-end documentation is so-called "facilitating documentation", which is usually never delivered to the user - this would include the requirement specification and the design specification. On the other hand, front-end documentation is developed for the user and includes:

  • Reference documentation like software technical reference manuals

  • Support documentation like user manuals, online help and installation guides

  • Interface text, or the labels that appear on the user interface (which also happens to be the subject of this article)

While each kind of documentation makes its own indispensable contribution to the application, interface text is like the first date that decides whether or not the user would like to take the relationship further. All the brilliant code that has gone into the application is put paid to if the user can't understand what a screen is supposed to do.

Interface text includes:

  • Titles
  • Field and button labels
  • Instructional text
  • Error messages
  • Confirmation messages

It should be noted that the above refers to text seen by a user only. There is, however, usually also a separate text-based deliverable, application messages, which includes the text displayed at the time of installation/configuration, console-based messages, e-mail notifications and reports sent by the application to the administrator. The audience for this deliverable is not usually the non-technical user, but the more savvy administrator, and this interface text is different from the rest in that it requires accurate technical understanding and allows for a greater degree of technical jargon.

Cheat Sheet

The process for developing all interface text is a largely iterative one, especially since, in real-world situations, there is only progressive understanding of the customer's demands. However, I believe the following ideas on both resource requirements and development process are fairly helpful:

  • At the time of capturing requirements, an effort should be made to acquire a set of internal documentation used or referred to by the users. This would be your best source for the vocabulary the users are familiar with.

  • Usually, a discussion of the manual processes that the application is supposed to automate or replace is done at the time of capturing requirements, and is a part of the requirements specification. Study this comparison to figure out which tasks/actions are going to change and how. Once you have ascertained this, you need to figure out how to word the changed tasks/actions so as to retain association for the users in the application.

  • Understand user profiles, especially the types of applications they have been working with in the past. This will give you a great idea of the terminology and jargon they are already familiar with.

  • The initiation of the interface development process is when the interface design team is asked to deliver an interface template for the prototype. This comprises:

  1. A template for the different kinds of screens in the application - the search screens, the forms, the confirmation screens, the configuration screens, and so on.

  2. Samples of buttons and control bars to be used across the interface.

  3. Fonts and decisions regarding the styling of the interface - typeface options, font sizes and colors to be used.

While developing the template for each kind of screen, the interface designers may pick up the most important ones and develop them fully, complete with control buttons, user input boxes and field labels. This, obviously, requires the interface text pertaining to those particular screens to be delivered in full prior to prototype completion.

The essential thing before you get down to making any deliveries, however "prototype" they may be, is to get your arms around the conventions to be followed for your interface text. The attempt should be to deliver something that is as well-cooked as possible, so as to exemplify in detail how the rest of the text is to be developed. Once this is done, developing the rest of the product will be streamlined and hassle-free.

Also, since the prototype is something the customer normally takes an interest in, this is a great opportunity to get feedback on the interface text - so again, the more refined the deliverable, the more real the feedback. Otherwise, whatever you deliver in the first shot is probably what you - and your users - will live with for a long, long time.

Matching It All Up

Having set the boundaries and the process for the delivery of interface text, it is now important to understand the approach required. Developing interface text requires two areas of knowledge: knowledge of the domain for which the application is being developed, and knowledge of the principles of developing good interface text. I'll address the first one, domain knowledge, right now and leave a discussion of the principles behind interface text to the second part of this tutorial.

I think you would agree that knowledge of the domain for which the application is being developed is essential - and by the time you are through with designing the application's labels and messages, you will have a thorough understanding of the processes which are being addressed by the application.

The important thing from the perspective of interface text is to imbibe the verbiage of the users and to understand the changes that your application will bring to their workspace...and how the changed aspects are to be worded to retain association.

What happens usually is that tasks otherwise manually performed by the users change drastically in appearance when they become application-enabled. Let's take a simple example: all workers in organizations submit vouchers for reimbursement of cash expenses. Enabling this in an intranet-based aoftware application would (most probably) require them to submit a form detailing their expenses for approval by the cashier, the cashier approving it at his/her terminal, and the amount getting deposited in the user's account as a result of the approval.

There are two levels of change being introduced by the application-enabling of this process:

  1. There is now no voucher in existence. What the users are filling and submitting is an online form.

  2. The actions required to perform this task change.

    • The user no longer gives a voucher to the cashier
    • The cashier no longer signs his approval
    • There is no separate act required by the cashier to deposit the amount in the user's account - the deposit happens via automatic trigger.

Now, if we were to consider the online and real-world equivalents for this task, we would have the following table:

Real-world Online
Voucher Expense form
Give voucher to cashier Submit
Sign voucher Approve
Dispatch cheque NA

In order to reduce user confusion and quickly familiarize them with the new world, the application's interface should use the original term for the task, and the newer, unfamiliar online terms for actions related to the task.

For example, here is a simple menu tree for the example application above:

Main menu
|-- Vouchers
     |-- Submit
     |-- Approve

Users know and expect that your application will change the way they do things. As long as your terminology is indicative and can easily be referenced against the old way of doing things, they will live with it, and probably learn to love the efficiency. But if your terminology is hard to understand, or makes them re-learn what they already know, they will hate you, your software and your organization. Making sure they pick door one, and not door two, is really the prime task at hand.

In the next article, I will be continuing this discussion with a quick roundup of the principles behind writing good interface text, together with a series of examples that will illustrate my point. Make sure you come back for that!

Note: Examples are illustrative only, and are not meant for a production environment. Melonfire provides no warranties or support for the source code described in this article. YMMV!

This article was first published on17 Mar 2003.