Best Practices for Writing Interface Text [Organizing Content #24]

In this ongoing series on organizing content, we’ve shifted from organizing help outside the interface to organizing help inside the interface. Moving help inside the interface has many advantages, and there are plenty of best practices for style and format. But the biggest shift in perspective, which I argued in my last post, is to stop differentiating between the interface and the help content. The interface is mostly text. It is an orchestra of words on a page that users rely on to navigate and understand the application’s content.

The first step in organizing help content is to refine the existing words on the buttons, tabs, labels, and dialog boxes. When those words aren’t enough, you can supplement the interface with more text to help users achieve their goals. Some technical writers refer to this supplementary text as narrative text, others as instructional text.

I don’t have a specific methodology for reviewing interface text. I’ve reviewed hundreds of student essays in my time, and despite the rubrics that departments dream up to objectify and standardize the review, rubrics always fall short for me. They’re an afterthought to try to organize your thoughts. I typically just read through a text and have a general reaction to it. Despite my resistance against rubrics, my thoughts on reviewing interface text can be grouped into five general areas: clarity, position, brevity, convention, and informativeness.


In looking at the words in an interface, pay attention to your gut reaction. Where does it not feel right? Are there phrases or words that jump out at you as being off? Oftentimes the interface fails to use the right word to describe an action or concept.

As I mentioned in my Technical Writer as Outsider post, determining what’s clear and what isn’t clear becomes problematic if you’re an insider to the product, having attended countless meetings discussing every aspect of the application’s terminology and design from the beginning.

Even if you’re an insider, as you look closely at the text in the application, read it carefully and analytically. Try to misinterpret it. See it as a new user might, and wipe away all your assumptions. What information is required to understand the sentences or labels? Where do you think users will become confused? Focus on these problem areas first. Replace obscurity with clarity. Switch clunkiness for plainness. Strip away fuzziness with accuracy.

In a culture of scanning and skimming, it’s easy to become desensitized to poorly constructed sentences and imprecise meaning. But when we put on our language glasses and look closely at each sentence and word to analyze its meaning within the context of the screen, we start to see the gaps more clearly. Knowledge of grammar and style is helpful in heightening awareness, but as Chris Atherton points out, even reading good writing can make your literary senses more acute. For example, after reading this psycholinguist’s essay — They get to me — about her love affair with pronouns, you’ll start looking more carefully at the words you use in your sentences.


Clarity isn’t just a matter of choosing the right words. Clarity also comes from putting the right words in the right places. Proximity increases clarity. The text you add should appear next to what it describes. Mike Hughes expands on this idea and says that users are drawn to action points on a screen. He recommends putting the text just a little “downstream” of the action point. In one of the best essays on user interface text, Instructional Text in the User Interface, Hughes argues,

User assistance occurs within an action context—the user doing something with an application—and should appear in close proximity to the focus of that action—that is, the application it supports.

In other words, position your help text next to the place on the screen where the user performs the associated action the help text describes.

Hughes says users usually skip static text positioned away from points of action. Their line of focus moves straight to the actions they can do on the page. The Microsoft Developer Network also echoes Hughes’ point:

Users tend to read control labels first, especially those that appear relevant to completing the task at hand. By contrast, users tend to read static text only when they think they need to. (User Interface Text: MSDN Library)

Practically speaking, you can forget about users ever reading the static paragraph that you add below the page title. They’ll move right past it as if it wasn’t even there and instead focus on the buttons and other actions they can do on the page. Add your help text next to those action spaces.


If there’s one undeniable principle in crafting interface text, it’s brevity. Interface text needs to be as brief as possible for two reasons: users tend to skip over large chunks of text, and the available real estate for help content on the interface is extremely limited. About all you have available is a tweet, or 140 characters. One tweet per screen, if you’re lucky. “Too much text discourages reading,” MSDN says. “The eye tends to skip right over it—ironically resulting in less communication rather than more.”

Because space is limited, you may need to provide a link to more information. A small help icon or link next to a point of confusion doesn’t tire the eye and allows you to expand on a topic without rigid space constraints. The help link can open a pop-up window in an online help or just provide a pop-up within the interface itself. The following screenshot shows how WordPress handles interface text for the Excerpt field, which appears below each post you write.

Moving text into the interface -- how WordPress handles confusing fields

Moving text into the interface — how WordPress handles confusing fields

Keep in mind that while your users may appreciate copious on-screen text the first time through, seeing the same abundance of text every time they perform a task on the screen can begin to clutter their view. This is one reason to use help links that open up more information: the help information only appears for those readers who need it.


Follow convention as much as possible. Your users have a history of expectations built up from thousands of hours of web browsing and application use. Users expect certain conventions that should probably be consistent in your application as well. Put the help button in the upper right. Use the standard names for buttons and labels, such as Save and Print.

One of my colleagues tells me that on one of his projects, the designer has decided to call the home button “Front” instead of “Home.” I’m not sure why. Following convention may seem a bit boring, but it decreases the learning curve for users. It’s one of the reasons Adobe tries to standardize their toolbars and interfaces across all their creative suite products — so users can carry over learning from one application to another.

When you’re stuck on names for buttons or other interface text, consult applications of a similar kind. For example, I was recently stuck on a button label in a calendar application I’m documenting. What word briefly describes the act of deleting “the current event and all subsequent events”? I checked out Google Calendar to see what term they used. While I didn’t use their exact term — “All following” — their usage helped me come up with a better solution.


One of the greatest challenges in editing interface text is locating all the messages tucked away in the dark corners of the application. Most often this hidden text appears as uninformative or illiterate error messages programmers have either written or ignored as they coded the application.

For understandable reasons, error messages slip by most checkpoints and make their way into production because they are hard to find. Many writers never see these messages unless they’re abusing the application. And once they appear, it’s hard to remember what you did to trigger the message. My favorite error message is “Object reference not set to an instance of the object.” This message seems to be pervasive across all .NET applications I’ve worked with. Though I’ve read and re-read this message dozens of times, I have almost no idea what it means.

How do you find all the messages in an application? How do you make sure you haven’t missed an error message, or an email notification, or an ungrammatical success message? Just because you don’t see it on the interface doesn’t mean the text isn’t there.

Sometimes programmers have a file that contains all of the language in an interface, especially if the application will be translated. Other times the messages are scattered throughout the application code. Quality assurance is no doubt aware of many of these messages, since they try to purposely break the application.

However you find the hidden text, when you do uncover one of these nuggets, they tend to provide golden opportunities for editing. I have rarely seen an error message or other notification that was informative. Usually these messages are phrased with as much obscurity and generality as possible. Programmers are sometimes careful to express in euphemisms what would otherwise be an admission of ignorance. Instead of “I don’t know why this error occurred. Sorry, maybe we’ll fix it someday,” users see “Unhandled exception has occurred in the application.”

Other times the reasons for the error are too complicated to explain in human terms. So we end up with “The conversation ended, or timed out, or resulted in a null exception.” It may be accurate, but it’s gibberish for users.

In Avoid Being Embarrassed by Your Error Messages, Caroline Jarrett recommends writing error messages in a way that tells users how to fix the problem. Piggybacking on Rhonda Bracey’s advice, Jarrett says,

… Try to give users some hint about what to do next, such as: Please try again, switch everything off and on again, jiggle the plug, uninstall the software, or whatever.

Jarrett cites an example. She says one writer changed a message from “Low Voltage Error” to “Check Power Cable.” The revised message focused on the fix rather than the problem and resulted in a “reduced support calls and certainly improved user confidence.” By focusing on the fix, you can make your interface text more informative to your users.

I’ve only scratched the surface with interface text. But if you stick with these five areas: clarity, position, brevity, convention, and informativeness, you’ll have a good starting point for improving interface text.

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

15 thoughts on “Best Practices for Writing Interface Text [Organizing Content #24]

  1. Ben M

    One point in this post is debatable to me: “Your users have a history of expectations built up from thousands of hours of web browsing and application use.” That may or may not be true. That said, following Web conventions is still favorable so that the product is consistent with what limited browsing the user may do—and it could help with future browsing. My dad, who is in his 70s, says that in his experience the term “user friendly” means that something follows expected patterns and conventions. The oft-used term “intuitive” really means the same kind of thing because very little in life is truly intuitive.

    My suggestion to any tech writers working on a project where they encounter something like the Front vs. Home issue is to see if you can get your hands on the application text once it’s coded. Our colleague told us that the rest of the project team, including the customer, doesn’t like the word “Front” used in the site Tom mentioned. When the site is coded, the text is out of the designer’s hands. Take advantage of that if you need to and save your users a headache.

  2. Patty Blount

    Since I began blogging, I’ve been describing the various changes my company and my team have been implementing. We’re shifting to Agile. We’ve been trying to “think outside the book by providing less traditional communication vehicles like videos, and we’ve been exploring ways to more effectively engage and converse with our users instead of “at” them.

    Each of these efforts introduces a set of challenges. For example, how do we prime an audience used to PDF libraries to now look to the internet for HTML-based information? How do we streamline our publication processes so the information is ready when the code is?

    But the most challenging of these is breaking ourselves out of the believing that all we do is write manuals.

    I am the most socially active of my colleagues so I comb blogs and mind Twitter and various RSS feeds looking for information that helps us manage (and, overcome) these challenges. I’ve been using your Organizing Content series as a bible of sorts. I’ve learned more from your blog than any where else, including grad courses.

    The timeliness of these posts is spot-on. I am right now designing a Help system for a brand new product, but there are still many who keep pressing for the old PDF.

    1. vs


      I’m in a similar situation. I’m new to the Agile environment, and I’m trying to get my team to move to non-traditional modes of providing documentation. Some of the things I’ve been trying to implement are Tooltips, Embedded Help Pane, editing Error Messages, writing Interface text, Video Documentation (Screencasts) – Tom has some very good articles on this.

      The main opposition, surprisingly, comes from within the Documentation team. There’s a lot of inertia. The idea is that, because one person is implementing all these new-fangled ideas, the whole new wave of documentation is person-dependent. Not a nice thing. If this radical writer leaves/gets busy/moves to other projects/has to delegate work to others, it’ll be a management nightmare.

      While I understand the skepticism, and sympathize with the constraints, it was very difficult to see my wings clipped.

      But the good thing is that others (non-Doc team members) were receptive, and the dust I kicked up has kept the momentum up. The rest of the Doc team is slowly converting, and might follow my doc suite’s lead now.

      My point is – being the lone evangelist (like you seem to be) is hard, frustrating, demoralizing, and I understand that (did I assume wrong?). But the rewards at the end of the day are soooo worth it. My conscious decision to move out of being just a ‘Technical Writer’ and be an ‘Information Evangelist’ did get me some weird looks, but I don’t mind being the Maverick. ‘To thine own self be true’.

      Tom, thanks for letting me vent.


  3. Techquestioner

    The least informative error message I ever encountered was in Wylbur, an editor program that ran in TSO on IBM mainframes. The message said, “Quiesce in progress.” After not finding any reference to it in the manuals, it took me 2 or 3 dictionaries to determine that it was the way a programmer with an excellent vocabulary chose to tell the user that the system wasn’t crashing, just quietly shutting itself down step-by-step.

  4. Patty Blount

    I can top that least informative error message. In Adobe Captivate, I encountered this error when converting output to .AVI format:


    That’s it. Just the word error in the middle of my screen. Many hours of research later, I learned it’s caused when the screen resolution is set to an odd number.

    I won’t even get started on the AuthorIT errors. *rolls eyes*

    I’ve been working on two Help systems. One is for an established product and the other is brand new. I’m using your Organizing Content series as my bible.

  5. Caroline Jarrett

    Hi Tom

    Loved the article, and was pleased that my piece about error messages was helpful.

    The one point where I’m not sure I completely agree is the bit in ‘position’ where you quote Mike Hughes, who “recommends putting the text just a little “downstream” of the action point”. I missed his article and was glad to read it just now. The example he uses puts the instructional text immediately after the box to fill in rather than in the preamble – which I agree is an improvement. Users definitely avoid reading preambles as much as they can.

    Only, I have also seen users struggle to find instructions placed after the box to fill in. Would probably be fine in Mike’s example of a username, because many users now know that creating a username is likely to be problematic and will look around for help on that (your point about convention, in fact). But for other, less familiar, questions – they may or they may not. I’ve seen users repeatedly fail to spot instructional text placed at the right-hand end of a long text box.

    Crucial point: position, as you say. Just not necessarily downstream.

    It’s also true that Mke improved the clarity and brevity of the message that he repositioned – and made sure that it was informative. Shows how all the different aspects you highlight have to work together.

    Look how those five come back: clarity, brevity, position, convention, informativeness – what a great set.

    Caroline Jarrett

  6. Tore Bostrup

    Good points – not only for tech writers but for developers.

    However – Vocabulary is important. Clarity comes from using the vocabulary that is best understood by the target audience, so there is a big difference between writing for the general public vs. for a specific business community. The “outsider” principle is only valid within the context of the target audience. Call things by the names users will know them.

    Eror messages tend to be a difficult subject. I absolutely agree with your conclusion – the user doesn’t really care about internal issues, but in addition to or in support of the “how to fix it” may want to know whether the action completed (none, partly, or fully) – the error may have arisen from displaying the success message or resulting data.

    But the developer (and support personnel) may need technical details, so error logging is typically as important to the _product_ as the error message is to the user.

  7. Pingback: links for 2010-08-26 « riverrun by meaghn | beta

  8. Richard

    “Object reference not set to an instance of the object.” This message seems to be pervasive across all .NET applications I’ve worked with. Though I’ve read and re-read this message dozens of times, I have almost no idea what it means.”

    Now that’s simple. Objects (as in object oriented programming) are basically just a number of bytes somewhere in the huge memory of the computer which are (hopefully) filled with valid and meaningful values. Objects are constantly created and disposed of while the program is running and this error occurs when an object should be have been prepared beforehand and at some point in the program this unexpectantly turns out to be wrong. The reference does not point to a prepared piece of memory.

    But you got several things wrong here:

    1) This message comes right from the .Net framework. You can sift through the source code all you like, you will never find it there.

    2) The system does not know anything about the Program’s context or what the user is trying to accomplish. It can merely state the facts and it’s up to humans to figure out, how those facts fit into the business at hand.

    3) Due to the complexity of most programs, it’s impossible for the developers to foresee what error can possibly arise at any arbitary point in the program. Therefore there is a ‘safety net’ which trys to catch all unexpected errors. Again, the system error messages merely state what has happened and where it has happened. Any further interpretation is impossible at this point, as the error is supposedly unexpected and further analysis is required before anything else can be said.

    4) “Unhandled exception has occurred in the application.” – This one you got all wrong. It’s not the developers who don’t know what’s going on (thanks a lot :-)). It’s once again the system. You see, an error has somehow gotten past the safety net I described above. This is another unexpected error, caused by an unexpected error. At this point the system can again just report that the program failed to proberly handle an error and then shuts down the program to prevent further damage. The system does not know anything else about the causes or what might be done against it.

    Sorry for the rant. At least my strategy for unexpected errors is simple: Catch them all and log all information (what has happened, where has it happened, when has it happened). Then I show the user a message that informs him that an internal error has occured which he cannot resolve. Instead he is given the option to send the logged information in an error report, so that a developer can analyze the problem and correct it. And yes, that’s admitting that our program obviously has a bug.

    1. Larry Kunz

      Richard, you’ve made a key point. Messages originate from all over. Well-designed applications catch those messages and put words around them to (a) identify the source of the message, if possible, and (b) give users an idea of what they should do in response. All of this falls under the rubric of what Tom calls “informativeness.”

      Not all applications have a safety net that’s as good as what you described. And even then, the great majority of computer users haven’t got a clue what the “object reference not set” message means. Whenever the application can add descriptive text to those kinds of messages, that’s a plus.

  9. Jonathan Chayce Dickinson

    “Follow convention as much as possible.”

    You want to be very careful of following convention too far; especially if previous conventions are less than optimal. I have to grapple with PM daily over interface and interface text because I want to veer slightly away from convention in high contention interfaces. Our religious use of convention makes our product more cumbersome than it should be. Your convention needs to evolve as your goals change.

    I like your use of MSDN examples; MacOS and Windows 7 are two great usable interface examples – but Apple don’t share any information or guidelines.

  10. Mark

    A good trick is to use the google keyword tool to see what phrases/labels most people use. 80% chance that’s the top label for your interface design.

  11. Pingback: Link-urile săptămânii 30 aug – 5 sept | Staicu Ionuţ-Bogdan - the Frontend Developer

  12. Tobie Openshaw

    My favorite error message of all time happened in the software company I work for, where a non-native English-speaking engineer wrote a joking error string that then didn’t get picked up in the review. It said something like: “Device not found. You dead.” This made it into the build and naturally the first customer to encounter it was NOT happy. Result was a patch just to fix that string.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>