Usability: How Technical Writing Succeeds

T. R. Girill
trgirill@acm.org
Technical Literacy Project
November, 2013 (ver. 2)

Handbook Table of Contents
Common Core Relevance

What is Usability?

Usability is a strange word but an increasingly influential idea. Any product designed for a specific purpose (such as tools, home appliances, or computer software) can be judged for success by its usability. For some people, improving a product's usabilty is a full-time job. In 2007, Barbara Whitaker featured usability professionals in her New York Times employment column (Whitaker, 2007), where she passed along this explanation of their work from Microsoft's Eric Danas:

We bridge the gap between what [any] technology is capable of doing and what users want to achieve.
A dozen different international engineering standards now endorse, describe, or apply usability for diverse industries. Most often cited is ISO9241-11, Ergonomic Requirements for Office Work with Video Terminals (ISO, 1996). This document inelegantly but clearly reveals the responsibilities of designers and the benefits to product users that usability imposes:
...[usability is] the extent to which a product can be used by specified users to achieve specified goals with effectiveness, efficiency, and satisfaction in a specified context of use.

Breadth of Importance

The diversity of professions concerned with usability reveals the breadth of its importance. Among the endorsing organizations and websites are:

Usability's Complexity

Usability is complex is a very distinctive way: it is multi-dimensional. Several largely independent (although sometimes casually confused) strands comprise it.

Barbara Mirel devoted a whole book (Mirel, 2004) to explaining why

are not the same. Both are necessary for product usability but neither alone is sufficient (and neither one entails the other). The international standard quoted above (ISO9241-11) already suggested that usabilty was threefold, requiring Other engineers have characterized these three dimensions of usability somewhat differently, or have suggested even more independent strands, such as This is not the place to referee alternative technical breakdowns of usability into its independent dimensions. Rather, we bring up its multi-dimensionality here for a special reason: to apply it to the usability of text.

Text Usability

Usability is an important property of nonfiction, nonnarrative text, just as it is of consumer products, software, or medical devices. The readers of technical text are also users:

Text usability has always been a background concern for writers and readers of technical prose. The computer boom of the 1970s, however, brought it to the foreground. For example, IBM was so often criticized for its unhelpful computer documentation that the company chartered a group of engineers at its Santa Teresa (California) Laboratory to explore how to improve IBM technical publications. The result was a 27-page internal booklet called Ease of Use (Ease of Use Study Group, 1979), which concluded that:

Cultivating such technical ease of use might seem obvious until one compares this text design strategy with the advice often found in technical writing books of the same period. For instance, consider Henreitta Tichy's Effective Writing for Engineers, Managers, Scientists (first edition 1966, second edition 1988). This was a very influential work, widely used in professional development courses for chemists or engineers. Yet despite 'effective' in its title, this book never mentions usability (or ease of use) in its detailed index. Tichy's very typical stress was on sentence-level style improvements (grammar and word choice). The book largely ignores "task analysis" and hence improving a technical text by overtly pursuing the three dimensions of usability championed above by the ease-of-use engineers.

Text usability's more recent influence shows in a different professional reference work that appeared a decade after Tichy's second edition, namely Developing Quality Technical Information by Gretchen Hargis (1998). Although this work has a general, comprehensive title, it focuses largely on computer (software) documentation. This is perhaps unsurprising because it was copublished by IBM, along with Prentice Hall. The 1979 ease-of-use themes shape all the topics and examples throughout this book. Indeed, 'ease of use' has replaced 'task sufficiency' as the label for the third essential usability (or quality) feature here. At 311 pages, this treatment is 10 times longer than IBM's pioneering pamphlet, but it stresses quite the same view that usability is the proper measure of success for all technical text.

Text Usability and Teaching

Several science teachers have successfully experimented with helping their students communicate better by trying various text-usability guidelines or checklists...but always indirectly and never by name. In one case, P.K. Rangachari and Sheela Mierson "developed a [one-page] checklist and used it to teach critical analysis of published articles" (Rangachari, 1995, p. S21) to college juniors in an undergraduate pharmacology course. In another case, physiologists Douglas Seals and Hirofumi Tanaka (2000) constructed a five-page, heavily annotated "manuscript review" checklist. Their goal was to offer their students a tool for "developing [the] challenging but essential professional skill" (p. 53) of effective text revision. Both of these cases implicitly exposed science students to text usability issues. But both focused exclusively on the formal features of professional journal articles and both assumed collegiate levels of disciplinary background knowledge.

For high-school students, however, overt text usability work can easily address much more basic skills applicable to a much broader range of science communication situations. Explicitly introducing students to usability when you teach technical writing helps them in two ways:

This diagram visually reveals the three dimensions, or independent aspects, of basic text usability, in the long "ease of use" tradition sumarized above:
basic text usability diagram

Easy to Understand

This is the most familiar usability aspect by far. Everyone has experienced struggling with technical prose that they couldn't understand (including students with inappropriate textbooks). To be understandable, text must be:

  1. Clear.
    Words or phrases that could easily mean different things to different readers (ambiguity) or that don't seem to have any clear meaning (vagueness) make text needlessly confusing for everyone and impossible for ESL readers.
  2. Concrete.
    Technical text often discusses abstract topics (sometimes by means of mathematical expressions). But even such passages can be made more understandable with the help of realistic cases, models, analogies, or tangible examples.
  3. Well Styled.
    This may seem like a literary issue encroaching on science prose. Actually, however, there are fairly simple heuristics (rules of thumb) for improving the style of technical text (see Bennett and Gorovitz, 1997; for example, prefer shorter Anglo-Saxon words to longer Latin-based ones when possible). And scientists who read English-language articles but who work primarily in another language complain often about the hurdles that careless styling imposes on their understanding (e.g., Montesi and Urdiciain, 2005).

Relevant

Writers sometimes forget that even if a passage is easy to understand, it is of little use to readers for which the content is irrelevant. Usable technical text anticipates the information needs (both scope and level) of the likely audience (a good cake recipe won't help those who want to cook a chicken). To be relevant for readers, text must be:

  1. Task Oriented.
    Most people read technical prose with an eye toward some planned future activity (perhaps specific and physical, like operating a fork lift; perhaps general and cognitive, like designing their next research experiment). Text oriented to the prerequisites, demands, and sequences of their likely tasks is more helpful than text that ignores those tasks.
  2. Accurate.
    Readers who rely on text for factual information expect tested procedures and reliable scientific claims and relationships.
  3. Complete.
    Balance is the key to usable completeness. Omitting needed steps or vital connections makes text unhelpful, even dangerous. Yet smothering those steps or connections in a flood of overwhelming or confusing detail undermines usabilty in another way. Relevant text omits nothing needed without including distracting stray information.

Easy to Find

This is the most overlooked aspect of text usabilty, and novice writers often neglect it. Yet even highly relevant text that is easy to understand is useless without effective access features. Accessibility really is a third, independent dimension of usability for science prose. Easy to find text has three characteristics (which, when they perform well, often don't call attention to themselves):

  1. Organized.
    Text structure is important even in story telling. For nonfiction nonnarrative text the structure may be less familiar to some readers (a problem-solution sequence or a hierarchy, for example), but revealing it is crucial for reader success. All writing involves planning, and for technical text planning the structure is as important as planning the content.
  2. Retrievable.
    Good text structure helps readers only if they become aware of it through navigation aids planned and installed by the writer (or by a subsequent editor). To help readers find relevant parts of a long or complex text, writers need to pay attention to:
  3. Visually Effective.
    Technical text often looks quite different than most prose fiction or even most newspaper stories (Bernhardt, 1986). Including appropriate pictures, drawings (e.g., of equipment), or data graphs is one aspect of making science prose visually effective. Integrating the text and graphics so that they truly complement each other's information delivery (with callouts and captions, for instance) is vital too. And managing data density using visual features to make text data rich without overwhelming readers is a constant challenge (e.g., see Tufte, 1983).

The Distance Comparison

Being easy to find and easy to understand (the presentation features) are important aspects of nonfiction text usability, but they play a different role than relevance (the content feature). You may help student writers balance their priorities among the three dimensions of usability by offering a comparison with distance.

In a 2013 post about "a new theory of elite performance," psychologist Christine Carter approvingly quotes colleague Angela Duckworth's revealing comparison of distance and achievement.

Duckworth starts with the familiar fact that

distance = speed x time.
From this equation it follows that even if speed is very low, with enough time one can still go any distance...as long as speed is not zero. That alone prevents time from helping one accumulate distance.

Likewise in general, psychologist Duckworth argues,

achievement = skill x effort,
from which it follows that even if skill is fairly small, with enough effort one can still compensate and reach significant levels of achievement...as long as skill is not zero. According to Carter, "researchers across diverse fields have produced remarkably consistent findings that back up Duckworth's [multiplicative] theory." (So there is empirical evidence that the tortoise's approach to winning (long) races against hares really works.)

For science communication purposes, we are interested in one specific type of achievement, namely the value of technical text for an intended audience. In this case the formula becomes:

	audience  =  relevant  x  presentation
        value	     content      quality
With strong parallels to the two "distance" formulas above, this implies that even if relevant content (in a student's draft text) is modest but not zero, presentation quality (understandability plus findability) will amplify its value for the audience (make it more usable). But where content is completely missing (or irrelevant to audience tasks or needs) then presentation quality, no matter how high, cannot rescue the text. (Scored sample short-answer nonfiction essays on Common Core tests, such as those in New York, illustrate exactly this formula.)

Hence, this prioritized approach to text usability prepares students well for writing outside of school, where presentation quality really amplifies relevant technical content but it cannot compensate for irrelevant (or absent) content.

Achieving Text Usability by Revision

In life beyond school, many people who write about science and technology increase the usability of their text iteratively, by repeatedly revising a quick draft to improve its usability features. This approach illustrates the benefits of viewing nonfiction writing as "text engineering."

As influential software engineer Frederick P. Brooks has pointed out (Brooks, 2010), early in the 20th century engineers often planned a device, then implemented their plan, then revised the prototype repeatedly themselves:

Edison fabricated working versions of all his inventions in his laboratory. Henry Ford made his own car. Wilbur and Orville Wright built their airplane with their own hands. [p. 176]
By filling all three roles--planner, implementer, tester--they were able to gradually discover ways to make their inventions more effective and more usable, ways that they could not have foreseen at the start.

Now, in the 21st century, many engineers can no longer fill all three roles personally because hardware implementation and testing today often call for special skills and equipment. But with (most) software, this feedback loop remains possible, and technical writing is much like software design. Your students can often achieve (improved) text usability iteratively, just like software engineers. They can plan and quickly draft "prototype" text, which they then repeatedly review, revise, and test on others to find and fix its usability weaknesses.

References

Bennett, Jonathan and Gorovitz, Samuel. (1997).
Improving academic writing. Teaching Philosophy, 20(2), 105-120.
Berhardt, Stephen. (1986).
Seeing the text. College Composition and Communication, 37(1), 66-78, reprinted in ACM Journal of Computer Documentation, 16(3), 3-16 (1992).
Brooks, Frederick P. (2010).
The Design of Design. Boston: Pearson Education, Inc.
Ease-of-use Study Group. (1979).
Ease of Use. San Jose, CA: IBM Santa Teresa Laboratory.
Hargis, Gretchen, et al. (1998).
Developing Quality Technical Information. New York: IBM and Prentice Hall.
ISO. (1996).
Ergonomic Requirements for Office Work with Video Terminals. Geneva, Switzerland: International Standards Organization.
Mirel, Barbara. (2004).
Interaction Design for Complex Problem Solving. San Francisco: Morgan Kaufmann.
Montesi, Michela and Urdiciain, Blanca. (2005).
Abstracts: problems classified from the user perspective. Journal of Information Science, 31(8), 515-526.
Rangachari, P.K. and Mierson, Sheela. (1995).
A checklist to help students analyze published articles in basic medical science. Advances in Physiology Education, 13(1), 21-25.
Seals, Douglas and Tanaka, Hirofumi. (2000).
Manuscript peer review. Advances in Physiology Education, 23(1), 52-58.
Sharples, Mike. (1999).
How We Write. London: Routledge.
Tichy, Henrietta. (1966, 1988).
Effective Writing for Engineers, Managers, Scientists. New York: John Wiley.
Tufte, Edward. (1983).
The Visual Display of Quantitative Information. Cheshire, CT: Graphics Press.
Whitaker, Barbara. (2007).
Technology's untanglers: they make it really work. New York Times, July 8, 2007. Available online at: http://www.nytimes.com/2007/07/08/business/yourmoney/08starts.html