Feature Article

Newsletter of the East Bay Chapter of STC May/June 2003	Dare to Be Dumb (and Write Usable Error Messages)

	by Rusty Jorgensen Northbay Chapter This article is reprinted from the March/April 2002 issue of northbay news, Northbay Chapter.
	It’s a tough time to be uninformed, dumb, or stupid: this is the Information Age, three centuries beyond the Age of Enlightenment. For most of us, the possibility of receiving a comment such as “That’s the most stupid question I’ve ever heard” is embarrassing and possibly threatening. Such comments inhibit our inquisitiveness and keep us from daring to display our ignorance. But inquisitiveness and curiosity are the foundation of good technical writing in general and good error message writing in particular. These days, you can’t stifle dumb questions and write well: the process of technical writing should influence product design as much as the final design influences the content and format of its documentation. To explore the relationship between dumb questions, good design, and good technical writing, consider “error messages” (on line, on screen, on paper).
From Error to Information Messages	In recent years, error messages have evolved from cryptic puzzles to readable messages; we’ve moved from “Error #911” to “Disk not ready.” Now it’s time for tech writers, armed only with dumb questions and a thick skin, to graduate from error to information messages. Error messages often are ambiguous and force users (and should force the writer) to ask dumb questions, such as “Why isn’t the disk ready? What’s ‘ready’ mean? Now what can I do?” In contrast, information messages are specific, sufficient, and answer users’ questions (“What went wrong? What now?”), but not without effort on the part of the writer.
No Time for Fear	The effort involved comes in setting one’s ego aside (this may be a small or large challenge), daring to be dumb, and asking the product designer, “What does ‘Disk not ready’ mean, and what should the user do?” The designer may say, “The disk is either absent, unformatted, or write-protected.” Based on that, the error message evolves to “Disk not ready: Make sure the disk has been inserted, formatted, and is not write-protected.” To redefine the nebulous “not ready” as absent, unformatted, or write-protected is a good step forward. However, the user still has only one chance in three of doing the right thing; two times out of three, he’ll see another error message, possibly the same one. No time for fear now. The next question is “Can we determine which of these three possibilities is the current problem?” If the designer answers, “No,” that may be the end of it. But, it's nice to confirm what one has been told: “So the machine can’t tell whether a disk is absent or present in the drive, right?” “Well,” says the designer, “actually we can determine that. We haven’t implemented the code yet but could pretty easily.” Assuming the code is implemented, we are left with two information messages: (1) “Insert the disk in the drive,” and (2) “Make sure the disk is formatted and not write-protected.” The next question, of course, is “Can the machine tell the difference between an unformatted disk and a write-protected disk?” “Sure,” says the designer, “that’s easy.” The writer thanks the designer and writes three specific, enabling information messages.
Contributing to Product Success	As a result of a few dumb questions, the writer contributes to the success of the product in several areas: Product improvement: less reliance on the documentation Documentation improvement: less of it; no need to explain or augment understandable, complete information messages Process improvement: stronger working relationship between writer and designer Individual improvement: better understanding of product. Dare to be dumb, it’s the smart way to work.

DMV Home \| EBSTC \| STC \| Contact Us An Online Project Information Solution \| Single-Sourcing, XML, Alphabet Soup – Help! \| Dare to Be Dumb Acting Locally, Thinking Globally in Literacy Outreach Project