This article was originally published in the May 2009 issue (Vol 14, No. 2)

About the Author

Patrick Lufkin is a senior member of STC and Chair of the Kenneth M. Gordon Memorial Scholarship for Technical Communication. He is currently co-manager of the 2008 Northern California Technical Communication Competition.

STC UUX Community Newsletter
Usability Interface

Usability Professionals Urged to Embrace the Value of Crafted Words

By Patrick Lufkin

This article was adapted and reprinted with the author's permission. The original article appeared in the December 2008 issue of Ragged Left, the newsletter for the Berkeley Chapter of the Society for Technical Communication.

User assistance has been moving in the wrong direction and needs to once again embrace the value of crafted words, usability guru Joe Welinske recently told a meeting of the Berkeley STC. Welinske's remarks came during a December, 2008, visit to the San Francisco Bay Area. While he spoke to a general technical communicator audience, his remarks were especially addressed to those concerned with usability and user assistance.

The problem, Welinske explained, is that the emphasis being placed on a plethora of new delivery technologies and content management systems-XML, DITA, XHTML, RoboHelp, Author-it and more-has led many to view information as just "content." When this happens, we lose sight of the importance of efficient communication, which only comes through craft.

Joe Welinske is president of WritersUA (formerly WinWriters), which provides training and information for user assistance professionals, through its popular annual conference and its website. He is the co-author of Developing Online Help for Windows, and has taught online help courses at the University of Washington, UC Santa Cruz, and Bellevue Community College.

Welinske said that his role in WritersUA allows him to talk to lots of people and to get a good perspective on what is going on in the industry. While there is a lot of creative energy out there, he said, we may be going in the wrong direction. He feels that something fundamental must change in how technical communicators approach their work, especially in the software industry.

More importantly, SharePoint has a lot of negative baggage. All those poorly organized, neglected, outdated SharePoint sites immediately come to the user’s mind. Do you want your SharePoint site mixed in with this negative baggage? No. You want your site to gather respect from your users. A little awe. Not a sigh and an “oh, another pathetic SharePoint site” response.

Thinking of information as just content, he says, moves us away from how we present information, and the quality of the information we present-how we craft actual words and phrases-which is what communication and writing is really about.

Writing, he said, is more than putting together a collection of words; it's identifying the best way to put words together, then going over it, crafting it, reworking it, trying to find the best combination that really gets the point across. We need to start thinking again about how to present our information in a more crafted way.

Welinske said that much of the resistance to expending time and effort on crafting communication stems from two popular misconceptions: 1) help systems are useless (or shouldn't be needed), and 2) people don't read (so why bother).

Welinske said the bad rap on help systems stems from experience with poorly crafted systems; poor help systems train people not to use them. Part of what we face, he said, is the lack of professionalism of those who have gone before us. Many help systems have been put together by people who weren't professionals and who did a poor job. But that doesn't mean that well crafted help systems won't get used.

A related, often-heard refrain says that applications or equipment should be so simple to use that people shouldn't need help. While there is no substitute for good design, he said, people who make this argument usually point to examples that don't actually do very much. Complex applications will always require user assistance, he said. But, he adds, that doesn't mean that you must document every feature, even those that are obvious.

The "people don't read" shibboleth, he said, ultimately comes from a misreading of a famous article by usability researcher Jakob Nielsen. Nielsen never said people don't read; what he said was that people rarely read online material in its entirety. Instead they scan, picking out individual words and sentences, looking for the information they need. People will read attentively when it helps them solve their problems and get their work done.

Welinske said that Nielsen's research is actually a strong argument for using more craft in user assistance, not less. You should give lots of thought to carefully crafting material to make it easy to scan. This can be done through the use of highlighted key words, meaningful subheadings, and bulleted lists. You should also use one idea per paragraph, and use an inverted paragraph style, starting with the conclusion or key idea.

Ironically, all this work, he said, may actually mean writing fewer words. One of the things that Nielsen found is that taking out extraneous words markedly improved people's comprehension. Based on this, Welinske has come up with a maxim of his own: "User Assistance will become most effective when we spend twice as much time writing half as many words."

But for that to happen, technical writers will have to reclaim their rightful place in the industry.

Welinske said that usability people and user experience people have latched onto an area that really belongs to writers. "Any word or phrase that appears on any piece of software anywhere in the world should be owned by the people in this room," he told his STC audience, "the people who call technical words and phrases their province."

We will also need to quit viewing writing as a commodity, an attitude that tends to value quantity over quality. While developing information we get too consumed with volume and the amount of information that we have to generate, rather than crafting the information.

The words-as-commodity viewpoint often expresses itself in a felt need to document every feature. Instead, Welinske said, we should ask ourselves: Is what I am about to write relevant to satisfying most users' needs? In most organizations, he said, most of the problems are caused by just a few things; those are the pain points we should concentrate on. We should skip the obvious stuff and, instead, identify the top five issues and solve the heck out of them.

In the long run, doing so helps the user and the company's profitability.

When we design the essential content better and cut words, he explained, we save further work all along the line. We have less to edit, to format, to markup, to test, to convert into other file formats, to translate and localize, and to update with revisions. Every word we add to our documentation set gets expanded tremendously.

In the long run, expending the effort to carefully craft what we produce is really the most efficient way to go.