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.

Clarity

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.

Position

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.

Brevity

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

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.

Convention

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.

Informativeness

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.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Although I try to write for a higher purpose outside of trying to get more readers and comments, I must admit that the interactivity of blogging is what makes it fun. To this end, I offer ten tips for increasing your readership:

1. Be patient. My friend Ben Minson is just starting out with his Gryphon Mountain blog. He currently has 4 subscribers, but he’s been writing excellent posts for the past 2 weeks, and he’s starting to get noticed. My wife has a witty, fun-to-read blog (whataboutmomblog.com), but only has 51 subscribers. To people who get discouraged at a lack of subscribers, I say be patient. It takes time to accrue readership. I have 471 472 posts on my blog.
2. Use Twitter and Twitter Tools. Twitter is the most surprisingly useful tool I’ve seen. I’m starting to check it almost as much as Google Reader. When I publish a new post, through the Twitter Tools plugin, that post is automatically published as a tweet on Twitter. Lots of cool people (e.g., Robert Scoble, Darren Rowse, Chris Pirillo) will follow you on Twitter if you start following them. Check out the Twitterati here. But really, you want to follow people like yourself. Through your tweets, they’ll pay closer attention to you and your posts.
3. Search-engine-optimize your posts. My site stats show about 65%+ traffic from Google. Google finds you by matching keywords that searchers use with keywords for your site (obviously). Pack your titles with search engine keywords. And use the WordPress SEO plugin to differentiate the title your readers see from the title Google sees. For example, this post’s Google title is more generic: Increase Subscribers to Your Blog — Tips for Increasing the Number of Readers. Boring, I know. But it’s the kind of string people search for. I want to be found.
4. Link abundantly in your posts. People check you out when you link to them. We’re always curious to know the contexts in which we’re being mentioned. The pingback brings people to your site, and if you look interesting, they subscribe. You’ll notice I’ve linked to everyone I mentioned in this post. Linking to people is like tapping them on the shoulder to get their attention.
5. Make intriguing titles. I find myself reading posts with interesting titles (for example, Dear WordPress, A Response to Your Letter). Even when the post is outside my category of interest, I’ll click a clever title out of curiosity. Copyblogger also has excellent advice about titles. I think learning to create intriguing titles is an important art in drawing readers in. (Holly Harkness reminded me of this lately.) Don’t worry so much about keywords and use the WordPress SEO plugin I mentioned in #3.
6. Catch the attention of people with influence. If you catch the right people’s attention, they can mention you on their site and boost your readership far more than you can alone. One of my earlier posts caught the attention of Joshua Porter (Bokardo), and overnight my readership grew by 80+ new subscribers. Some of the people I interview for podcasts (e.g., Anne Rockley) mention the podcast to their large readership base as well.
7. Use the Feedburner chiclet to watch your readership. I don’t watch site stats as much as readership stats. I’m convinced that good posts will naturally attract new readers. If my readership shrinks, I know my writing stinks. If it grows, it’s because the posts must somehow be worthwhile. People naturally link to interesting posts, which grows your readership. Without Feedburner, I don’t see how you can measure readership at all. (By the way, the numbers always artificially dip on the weekends. I am still inching toward my 1,000 mark.)
8. Leave comments on other blogs. I always check out the blogs of those who comment on my posts. And I try to leave comments on posts I enjoy reading, if only to let the person know that I read it. Commenting on as many blogs as possible is a tedious strategy for gaining readers, but when you’re new, you need make yourself visible. No doubt you read blogs already, so add a comment. Other commenters are also attracted by an interesting comment you leave, which leads more people back to your site.
9. Write a few home run posts. The best post I’ve ever written was 20 Usability Tips for Your Blog: Condensed from Dozens of Bloggers’ Experiences. It has 293 comments and trackbacks. I spent weeks writing it — it was the core of my presentation at least year’s Doc Train conference. It is certainly my home run post. Everyone has a home run post inside them. Rhonda’s is a little post about blueberry muffins, which has surprisingly attracted thousands of hits. When you write it, your readership will take off.
10. Write useful content. A vague assertion, I know. But if your information isn’t useful, practical, or somehow noteworthy and interesting, no one will subscribe. Part of the appeal of sites like Lifehacker and The Blog Herald is that they provide useful information.

Bonus Tip: If you want quick exposure, write a guest post for my blog. Simply contact me and send me either your post or an idea for one.

photo by cogdogblog