Looking for something?
By Sue Kocher, Carolina Chapter Senior Member
Editor’s Note: This article was originally published in the February 19, 2007, edition of words@sas, a series of articles about Terminology Management issues, published on the internal web site of SAS Institute Inc.
What do customers want from our software and documentation? They want to accomplish tasks, and to obtain information about tasks, as quickly and painlessly as possible. Do they also expect to be entertained along the way? No, not when there is work to be done. Years of usability analysis in the software industry indicates very clearly that clarity and ease-of-use is topmost on the minds of software users. Sure, software users appreciate a look and feel that is aesthetically pleasing, even beautiful. At the very least, they want a user interface design that says “quality.” Bells and whistles are nice, as long as they’re functional. But when it comes to getting work done, most of us wish that cute little animated PC would stop cartwheeling and get the heck out of the way when we jab the
!
A crucial key to the usability of both software interfaces and written material is consistency. The software industry is slowly realizing that technical information is far easier to digest and use if it is predictable. In fact, this is true of language processing generally: in order to understand speech or writing, the brain is constantly engaged in a rapid-fire testing process, predicting or “precomprehending” what is likely to come next, according to what has been understood already. Furthermore, most people read text not word by word, but in chunks. We learn to recognize the “shape” of printed phrases and sentences. That way we don’t have to stop and sound out each word in our heads, or ponder its meaning.
What we want to give our customers, so as not to unduly wear out their brains, is an experience with our products that includes enough “new” information to complete the task efficiently. For this, we must be consistent and predictable wherever possible.
The following examples of consistency issues focus on user documentation. However, the same principles apply to all “language resources,” including the text in user interfaces, in marketing materials, and even in e-mail communications.
We slowly gave up our inclination to use idiomatic speech, and of course we had to learn the lingo associated with software and particular products. We finally came to realize that there was no need to slavishly follow the old adage, “Say what you’re going to say, say it, and then say what you said” for the simple reason that most users do not read our documentation from start to finish in a serial manner.
But it was hard to dispel the feeling that repeating the same sentences and phrasing multiple times in a single document would be “boring” for our users. Writers sometimes protested that their creativity was being stifled if they were asked to express the same concept or task the same way each time, for the sake of consistency.
But in the same chapter, you might also find these:
… and any of a myriad other possibilities. Does this make technical documentation “more interesting”? No, but it makes the tasks more exhausting and time-consuming to find and to learn, because the words in each sentence must be read and “parsed” carefully. Even more mental effort is required to understand that all of these sentences are saying the same thing, and that there is a pattern in this chapter for presenting task instructions.
Over the past few years, the SAS Publications Division has come a long way toward standardizing what and how we write. In addition to our comprehensive Style Guide for User Documentation, we now have templates for different types of books, so that users can predict what kind of content a book offers by its title. Developing standards for topic titles was a challenge that took over a year to complete, because everyone had their own “standards”, often well thought out, but that clashed with one another. Our documentation looked like it had been written by several different companies, with completely different ways of organizing and presenting information.
Now users can scan a Table of Contents or a list of search hits to quickly find the task or conceptual information that they need. As writers and editors learn to apply the guidelines, our user documentation continues to improve in clarity and searchability.
Imagine how much time, effort, and human resources can be saved by using “copy and paste” to recycle the same message. Imagine how much more smoothly our solutions will work together if they all use similar labels, messages, and designs—that’s intelligent reuse. Far from stifling creativity, the use of consistent phrasing frees writers and developers to focus their creative efforts on making complex concepts and tasks more “user friendly” and effective. Software is complex, because it accomplishes complex tasks for ever-changing markets. Our job is not to impress the user with how huge and dauntingly omnifunctional software is. Our job is to make complex tasks look easy, and to give the user lots of a-ha moments (Ah, I’ve done that before, I know what that means!) along the way.
Sue can be reached at Sue dot Kocher at sas dot com.
Sue Kocher
What do customers want from our software and documentation? They want to accomplish tasks, and to obtain information about tasks, as quickly and painlessly as possible. Do they also expect to be entertained along the way? No, not when there is work to be done. Years of usability analysis in the software industry indicates very clearly that clarity and ease-of-use is topmost on the minds of software users. Sure, software users appreciate a look and feel that is aesthetically pleasing, even beautiful. At the very least, they want a user interface design that says “quality.” Bells and whistles are nice, as long as they’re functional. But when it comes to getting work done, most of us wish that cute little animated PC would stop cartwheeling and get the heck out of the way when we jab the
!
What we want to give our customers, so as not to unduly wear out their brains, is an experience with our products that includes enough “new” information to complete the task efficiently. For this, we must be consistent and predictable wherever possible.
The following examples of consistency issues focus on user documentation. However, the same principles apply to all “language resources,” including the text in user interfaces, in marketing materials, and even in e-mail communications.
Consistency in Documentation
Not so many years ago, technical writers and editors shared a set of assumptions about “good writing” that were mostly instilled by creative writing teachers, or by training in academic research writing. We realized, of course, that technical writing is more formal and straightforward than prose for art or entertainment, yet not as formal or wordy as the language of an academic paper. But we clung to some old habits.We slowly gave up our inclination to use idiomatic speech, and of course we had to learn the lingo associated with software and particular products. We finally came to realize that there was no need to slavishly follow the old adage, “Say what you’re going to say, say it, and then say what you said” for the simple reason that most users do not read our documentation from start to finish in a serial manner.
But it was hard to dispel the feeling that repeating the same sentences and phrasing multiple times in a single document would be “boring” for our users. Writers sometimes protested that their creativity was being stifled if they were asked to express the same concept or task the same way each time, for the sake of consistency.
How Many Ways Can I Say “Do This”?
Suppose a User’s Guide includes instructions for completing a number of tasks in “Display mode.” In some legacy doc from the old days, you might see a nice, clear sentence like this:To (do task A) in Display mode, complete the following steps:But in the same chapter, you might also find these:
In Display mode, you can also (do task B) by completing the steps below.Follow these steps to (do task C) in Display mode:(Task D) can be accomplished in Display mode by working through the following procedure:… and any of a myriad other possibilities. Does this make technical documentation “more interesting”? No, but it makes the tasks more exhausting and time-consuming to find and to learn, because the words in each sentence must be read and “parsed” carefully. Even more mental effort is required to understand that all of these sentences are saying the same thing, and that there is a pattern in this chapter for presenting task instructions.
Over the past few years, the SAS Publications Division has come a long way toward standardizing what and how we write. In addition to our comprehensive Style Guide for User Documentation, we now have templates for different types of books, so that users can predict what kind of content a book offers by its title. Developing standards for topic titles was a challenge that took over a year to complete, because everyone had their own “standards”, often well thought out, but that clashed with one another. Our documentation looked like it had been written by several different companies, with completely different ways of organizing and presenting information.
Now users can scan a Table of Contents or a list of search hits to quickly find the task or conceptual information that they need. As writers and editors learn to apply the guidelines, our user documentation continues to improve in clarity and searchability.
Being Creatively Consistent, and Consistently Creative
Sue can be reached at Sue dot Kocher at sas dot com.
Top of page
Staff and authors:
