The programmer as wordsmith -

The programmer as wordsmith

The text our applications display to the user has a huge effect on usability and so deserves your close scrutiny during development.

The representative of my local power company has just been on the radio, defending a glitch that caused some customers to be overcharged. His explanation centered around the fact that the meters in these homes had not been “recalibrated” when the new pricing structure was introduced. The radio interviewer later referred to the “adjustment” to the meters. The power company guy failed to take the hint that only a tiny percentage of listeners would have any idea what recalibration meant. No doubt he was from an engineering background and felt that it was more important to be technically precise than to be understood. In design documentation, I would insist on using the more precise term, and if the reader didn't understand it then it's up to the reader to further his education until he can fully understand the topic at hand. When communicating with the general population the priority is very different. Being understood by a large percentage of the audience means hiding some of the engineering details.

Too many engineers forget that most people don't speak their language, and we shouldn't force our customers to learn a new lingo to use the products we produce. The English text that appears on so many products is written in the voice of the engineer, rather than explaining itself in terms meaningful to the user.

The text your application displays to the user often has a bigger impact on usability than any other factor. Technical terms that baffle the user will leave them feeling confused and intimidated. Inconsistent use of terms leaves them wondering if the “settings” referred to in one menu is the same as the “configuration” referred to elsewhere in the interface.

The engineer will see many things from the point of view of the device, rather than that of the user. The word “user” itself is a typical example. The person interacting with the device would rarely refer to themselves as the user. But many devices have an option called “user settings.” It almost always means “device settings” since it's the device and not the user that's being configured. In most cases the term “settings” on its own is better.

Programmers also allow the implementation to show through in their choice of words. When an application says “enter a string,” the wording was influenced by the fact that programmers manipulate strings as an implementation detail. The user is more likely to be entering some information, such as a name. The type of information the user will be entering is the term the programmer should use.

C++ has influenced programmers to use the word “new” where they should really use “add.” When I'm entering someone's phone number in the memory of my phone, I'm creating a new entry, and probably creating a new data structure in which to store the details. But the average user doesn't know or care about the data structure. Calling a menu option “new” suggests that the person or the contact details are new—when in fact I may have known them for years. The person's contact details have existed for a long time, but I now want to “add” them to my contact list.

The terms “set” and “reset” have specific meaning when referring to the state of a bit or a latch. Engineers understand them but not the rest of the human race. Figure 1 shows the clock on the dashboard of my car. For most people it would be less confusing if the buttons had no labels and you simply fiddled with the buttons until you got it right! In fact, the “set” button moves the time forwards one minute at a time and the “reset” button clears the minutes value to zero, without changing the hours value—go figure.

Figure 1: Car clock with set and reset buttons

Point of view
In some cases an interface will address the user as “you” or refer to some of the configuration as “your phonebook.” An alternative is to treat the device as something that the user is manipulating in the first person. So the user would have “my phonebook.” I've always considered using the first person as less formal. This use of “your” and “my” is quite popular on web sites, though there's no consensus as to which is preferable. If you choose to use the first person for “my phonebook,” you need to be consistent when giving instructions. So the instruction “You must enter a name” becomes “I must enter a name.” This starts to sound as if the device is trying to echo your thoughts and will strike most users as weird.

Point of view is also important in other ways. One product with two CPUs displayed the message “Test mode requested.” This message displayed after one CPU requested the other to enter test mode. Usually a short delay followed so it was important at this point to let the user know that he was expected to wait. At first I couldn't figure out why the message just didn't seem right. The problem is that the request for test mode is sent from one CPU to the other. The user didn't need to know that the device contained two processors and certainly couldn't be expected to appreciate that one processor had to request test mode so they could synchronize. “Entering test mode” would have been far more appropriate. As it turned out the user usually thought that the message was confirming that the user, and not one of the CPUs, had requested test mode.

All text should always be addressed from the system to the user. Don't expect the user to understand that some text messages are coming from one part of the system and other messages from another part.

Similarly, if you use messages of the form “Waiting for . . . ” make sure it's obvious whether the expected action is to come from the user or some other source. “Waiting for confirmation” could leave the users wondering if they need to press “Accept” to confirm their last request or if the system is waiting for a remote credit-checking system to validate their credit card.

The user's point of view is also important when he declares his current state or declares the desired state. I encountered one air-conditioning system that had two buttons for adjusting temperature. They were labeled “Too hot” and “Too cold.” I think the designers were trying to appeal to the less mathematically minded by avoiding “+” and “”. However, their good intentions went wrong because users were likely to misinterpret what the two buttons did. The user was expected to select her current state rather than selecting the temperature she desired—when the user pressed the “Too cold” button, the system started to increase the temperature. For instance, if a person wants to be too hot so that he can take off his coat, he might press the “Too hot” button but will find it has the opposite effect. The user selected what he wanted rather than indicating the current state of the room.

A more likely mistake is that a user will want heat, see a button with the word “hot” on it, and press the button without giving any consideration to the adjective in front of it.

Many devices have PC-based configuration utilities that allow the user to save or restore calibration data and configuration details in a file on the PC. On one project I worked on, we used the terms “Upload” and “Download” on the buttons that transferred the data. We soon realized that there was no obvious interpretation of which direction was “up” and which was “down,” so we replaced them with more explicit labels such as “Copy to PC” and “Write to Device.”

Spell checkers are standard in word processing and other office applications, but they're unusual in a programmer's integrated development environment (IDE). I notice that the CodeWright editor allows you to run a spell check that only applies to the quoted strings in the code. If your editor doesn't have such a feature, it shouldn't be difficult to extract all strings and place them in a word processor to check for misspellings. Depending on your programming environment you may enter the strings in a drag-and-drop IDE and store them in a resource file so the strings won't appear in your code but can be accessed in some way as plain strings. Don't forget to apply the spell checker to the translated versions of strings when your product is being marketed in more than one language—though this is a job for the translator, not the programmer.

On small displays you might be restricted to a fixed number of characters. Text displays that are 20 characters wide are popular but make fitting the strings quite tricky. Using abbreviations has to be done carefully to avoid causing ambiguity. Using “No.” for number can be confused with “no,” a negative. (You might wonder why “No.” is a common abbreviation for number, when the word “number” doesn't contain the letter “o”; the origin is the Latin word “numero.”)

Another way of representing number is the # symbol. Unfortunately this is referred to as the pound symbol in the U.S. but is called the hash symbol in many other English-speaking countries. This difference can lead to confusion if instructions are spoken, as is often the case when an automated telephone response system instructs the user to press the # key on their telephone.

Another abbreviation that I dislike is shortening the word “temperature” to “temp.” This could be an abbreviation for “temporary.” Sometimes the abbreviation works in one context but fails in another. This complication is annoying because it's obviously preferable to use the same abbreviations everywhere.

Author, author
The programmer who writes the software is often not the person who is best qualified to write the English text that will be visible to the user. Just as professional technical writers are employed to produce user manuals, they should also be involved in the production text displayed by the software. In many cases it's not practical to have the technical writer involved at all stages of the product development. Often it makes more sense for the programmers to produce the text as they're developing the interface but later have a review of the text to make it suitable for human consumption.

During reviews of text, watch out for strings that are similar but not exactly the same. If one place in the design says “Cancel using X” and another says “Press X to Cancel,” you can improve the interface by using exactly the same term in both places. When writing software this often means that you reduce two strings to one and refer to it from multiple places in the program. If the strings are similar, but in fact the meaning is different, you should try to make the strings as different as possible to minimize confusion.

During reviews always watch out for words that might be common in the engineer's vocabulary. Your target audience may not understand terms such as “default,” “mode,” and “buffer.” If you're not sure what your users will understand, you need to spend more time talking to them.

Maintaining a glossary is good practice. A user glossary is a good way to keep a clear boundary between terms that are meaningful in the user's world and those that are part of the engineer's description of the internals of the system. The definitions in the glossary facilitate consistent use. Sometimes you wonder if the “screen” is the physical display or is it one of a number of pages between which the user navigates. Do we show the user a “Menu” or a “List.” If different programmers and technical writers fail to use these terms consistently, the user suffers.

For some reason, in PC applications, the registration key is an item that receives a variety of names. The same product will refer to it as an “authorization key,” “activation code,” and “installation key” in various parts of the documentation, labeling, on-screen help, and in the dialog where the user is supposed to enter this number. While all of the names are valid, the team should be able to pick one and stick with it.

Speaking in paragraphs
In cases where you find yourself writing full sentences, rather than just labels on a user interface, a whole new set of skills is required. Features such as information kiosks or online help for your device require a lot of text and thus move much more into the realm of technical writing than user-interface development. For anyone who spends time writing at length I highly recommend the Plain English Campaign at Each year they bestow Golden Bull awards for companies that foist unintelligible gibberish on their customers. Most of the awards are presented for language used in correspondence or user manuals, but I imagine that they're going to see more entries for text displayed by software applications and embedded systems devices.

Writers block
Compared to a PC application, an embedded system often has to communicate its message in a small space with few words. Choose those words carefully and your users will thank you for it and remember Nathaniel Hawthorne's words: Easy reading is damn hard writing.

Niall Murphy has been designing user interfaces for 12 years. He is the author of Front Panel: Designing Software for Embedded User Interfaces . Murphy teaches and consults on building better user interfaces. He welcomes feedback and can be reached at . Reader feedback to this column can be found at .

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.