Copyright 1991, Baywood Publishing Company, Inc. All rights reserved. Permission to reproduce beyond the guidelines of "fair use," in whole or in part, must be secured in advance from the publisher.
While much of this book concerns techniques for writing good software documentation, attention must also be paid to the fact that one cannot write good documentation for bad software. Manual writers, being essentially teachers, have a unique and valuable perspective on what makes software easy to learn and use and therefore easy to document. Capable and venturesome writers can thus have a hand in screen design and command wording, and even work alongside engineers in basic product design. Although some may find this new role intimidating (and others may find that it compromises objectivity), it is really just another form of communication -- the communication between man and machine.
The influence of the outsider -- that is, anyone with more perspective on a design than the nuts-and-bolts people who are building it -- is critically needed. To the user, a bad interface can mean many things: inconsistency of wording within a computer program can mean frustration, for instance, and poor control placement in an airplane cockpit can mean a "smoking hole in the ground." But to the vendor, a poor user interface means only one thing: trouble. Unhappy customers. Sales lost. Perhaps even lawsuits filed. Appliance etiquette is indeed too important to be left to engineers, even though their skills are necessary to it.
In this mechanized world, examples of good, bad, and indifferent human- factors design are all around. Once you get used to looking, you can learn from almost anything -- the cockpit of a jetliner, the inside of your own car, and, last but not least, software.
The most basic requirement is that the product ought to work. The finer points concern how well it works, how easy it is to learn and use, how well it interacts with other products. But a great many software products have outright "bugs" that corrupt data, crash the computer, or otherwise stumble at this initial hurdle. Because of the technical complexity of software bugs and the strong financial pressures to ship a new product, these defects are difficult for the writer to address. (Users of personal computers have an especially acute awareness of how software is rushed into production to meet some real or perceived "market window.") But if these basic problems are not spotted and corrected, the entire development and marketing effort can be for naught.
The results? Customers who express faith in the company and enthusiasm for the product are shafted. Competitive products gain ground on the hapless program (which might have been rushed out in the first place because a marketing manager, with or without adequate technical information, thought time was of the essence.) And there is the stress placed on the development team as they rushed to get the product out, only to find themselves scrambling to repair it. The whole affair is likely to be an avoidable disaster both within the company and in its public relations. A product and a company get a black eye by failing to meet the fundamental requirement of user friendliness: robust operation.
The consequences can be even worse than that; witness the patients treated by a lethally rude appliance at the East Texas Cancer Center in 1986. As reported in IEEE Spectrum, [1] miscommunication between a radiation treatment machine and its operator helped cause radical overdoses of radiation. Software that did not carefully reconcile the data entered at the console with the actual settings of the machine, combined with what Spectrum calls "undecipherable" error messages, contributed to the death of one patient and the serious injury of another.
Ironically, the software problems resulted from an ill-considered attempt to increase the user friendliness of the machine. Previous versions had required operators to reconfirm their choices at the console each time they adjusted the magnets that actually controlled the radiation beam. The "improved" version allowed them to circumvent this safety procedure. (The machine, a discontinued model from the medical division of Atomic Energy of Canada Ltd., has since been festooned with safeguards intended to steer the operator in the right direction and protect the patient from any mistakes that slip through.)
Admittedly, that fiasco was extreme, but problems may be found to some degree in many products. Usually there is a quality-assurance or engineering test department that serves as a "bug filter." Such departments are generally staffed by engineers who work with the development team; they can use their knowledge to look for arcane problems of reliability and interoperability. (Note the difference between engineering test and production test. The latter involves checking on the production line and is a different matter entirely. Success or failure in our work comes during engineering test.)
Theirs is a difficult task; computers are far and away the most complex and subtle of man's creations, and it is only natural that they should have bugs. But most bugs can be eliminated before shipment, and conscientious software developers go to great lengths to do so.
If an engineering test department does not exist, or if its aims are subverted by nearsighted or venal executive management, or if it merely proves itself human and fallible, a buggy product will be shipped. You may wish to alert the appropriate people when you spot a problem, and conscientious companies encourage this. But having said so, we'll assume that the basic quality of the product is being tested elsewhere; we shall concentrate on the polishing of its user interface.
This is where the technical communicator can play such an important role. User friendliness is not necessarily amenable to being taught in school: the main reason is that it tends to be highly specific to some product. General principles can be taught, but beyond that, it takes a lot of nosing around the design, looking at what works and what doesn't.
Let's examine mechanical human factors first, since mechanical things are more familiar than software. Looking at blueprints or fiddling with a prototype or a mock-up, you start asking questions. How easy is it to put it in? What is the penalty for putting it in upside down? Can it be designed so it can't be put in the wrong way? How stout can it be made, and at what price? Is there a standard that can be followed so people will be familiar with the thing?
The engineers on the project may or may not be very good at looking into these problems.[2] That's where industrial designers come in. They are to mechanical engineers as architects are to civil engineers -- the people who design usability, attractiveness, and (presumably) grace into mechanical objects.
Take for instance the power antenna on my 1979 Chrysler LeBaron. When the antenna failed, I found that it could not be removed without first taking the fender off the car. This was no problem during manufacturing, since the antenna was installed before the fender, but it would have been such a pain in the neck to repair that I decided not to fix it at all. A graceless design resulting in an ill-mannered machine, it is a sad statement about what some car companies really think of maintainability. No one caught the problem on the blueprints (or in the preparation of the maintenance manual). Or perhaps no one cared, or someone cared but was not listened to.
That is just one example of the ill-mannered machines all around us. Other problems could have been foreseen and avoided by a technical writer looking at the situation from the user's viewpoint. Design checking for ease and correctness of use is a fairly common practice, but the engineers don't necessarily have the best approach. Even if their basic approach is sound, they don't always see the little things, any more than technical writers can see the shortcomings of their own manuals. The designers need an editor.
Design examination also takes place in the software world, although the details are different. When reading the initial specifications, you think about the logic of the thing -- what it does and how it goes about these tasks. You can apply the skills of your own writing specialty to the wording of the screens, prompts, error messages, and so forth.
As the software begins to take shape, perhaps the programmers will provide an emulator -- a mockup that behaves as though it were actually processing data. Armed with the emulator, you can start trying out the product as if you were a user. Time and money permitting, it helps to videotape a few naive users as they try out the emulator or an early version of the software itself, much as you might test a manual.
Some of these steps probably sound familiar; they are well known, if not always well adhered to. Further, unless you work for one of those benighted companies that still look upon documentation as a last-minute task to be rushed through just prior to product delivery, you probably already read specifications and use emulators. Offering feedback to the development team is a simple extra step if you have the inclination. Although it is outside the mainstream of professional practice in the technical communication field, such design involvement is nothing new, and has become a topic of considerable interest, as evidenced by its prominence at professional conferences.[3]
Many of the details of user-friendly design may seem trivial, fussy, or nitpicking. So does proofreading, a task which most writers take seriously. User friendliness depends on the big items, the sexy items: the basic paradigms of the interface and the overall flow of the procedure's logic. But an elegant overall scheme will fail if the details are botched.
Think about the programs in your life that were the most aggravating or the hardest to learn. Chances are that you were stymied by little things: Menu items that gave no clue as to their functions. A lonely shortcut based on a command noun surrounded by shortcuts based on the verbs. Error messages that might as well have been written in Urdu. The "big picture" aspects are important, but with program, as with machines, friendliness is often defined as the sum of the petty aggravations. Fortunately, especially for "interface editors" who come in late in the development cycle, the little things are the most amenable to correction.
Sometimes the user-interface designer has to make a decision between two good alternatives, like the noun-verb paradigm exemplified by the Macintosh versus the verb-noun orientation of the IBM Personal Computer. But sometimes the tradeoffs between standardization and optimization are more severe. Let's look again at a mechanical analogue.
On the aforementioned Chrysler, the parking brake release handle is right next to the parking brake pedal, and is the only control in that area. On a friend's 1980 Cutlass, the handle closest to the parking brake pedal releases the hood; I pull it by mistake all the time. The Chrysler scheme is more intuitive. But General Motors has sold far more cars -- in the language of computer marketing, their "installed base" is much larger. Is it better to engineer an optimum solution or to adhere to a flawed standard that many users are familiar with? This is a common and vexing problem; a suggestion for improvement might seem wonderful when the product is considered in vacuo but not in the context of marketplace expectations and a company's product history.
Sometimes there is not even a flawed standard. Take, for example, the terminal emulation software that enables microcomputers to communicate with mainframes. Most sophisticated terminals have function keys that do not map cleanly and uniquely onto personal-computer keyboards. For various reasons, one of the most important of which is corporate desire to be different from the competitors, each terminal emulator seems to do this differently.
The moral of the story? Research the field, either formally or informally. You might find de jure or de facto standards (or sometimes both in contradiction to each other). You might find multiple quasi-standards, or a de facto standard from a competitor that is politically unacceptable in your company, or perhaps no standard at all. But even if you find no suitable standards and advocate a different scheme, it pays to size up the available conventions, examining each in light of the projected audience.
Once the basic paradigm has been chosen and the standards have been identified, the detail-work begins. As is so often the case in writing, consistency and accuracy can make or break the product.
In Please, a PC database program sold by Hayes Microcomputer Products that I once used, pressing Return indicated completion of a text string and entered it into the database. Some multiple-choice items, though, were specified with single characters. With commendable (though misguided) concern for the user, the programmers thought they would save a few keystrokes by automatically accepting those entries without the usual Return. Time and again, I would type a Return, which the program then dutifully applied to the next menu.
Fortunately, that did not cause any harm, just a little aggravation (especially during rapid-fire data entry). Some user-friendliness shortcomings are not as forgiving. Witness the Disk Operating System, or DOS, for the PC.
In most operating systems, commands that deal with strings of text can include characters called wildcards. A wildcard tells the system to skip over a certain portion of the string when deciding what all the command should affect -- in this case, to accept any file that matches the other criteria. For instance, ERASE *ROLL.DAT erases all files whose names end in ROLL.DAT.
Wildcards are a great convenience for the user, but the wildcards in DOS, or at least some versions of DOS, have a hidden "gotcha." Not having read the manual (and who reads manuals?), one might think that a wildcard in the middle of a filename, like ERASE PAY*LL.DAT, would cause DOS to search by the two remaining criteria and erase all files starting with PAY and ending with LL.DAT. (The "extension" .DAT is parsed separately from the filename proper.) Under this reasonable assumption, files with names like PAYRCRD.DAT and PAYRATE.DAT would not be affected. This is not the case. DOS, or at least some versions of DOS, won't parse a segment of a filename that comes after a wildcard. ERASE PAY*LL.DAT erases all files beginning with PAY and ending with .DAT, which could come as a rude surprise.
Machines, however, are man's servants, and servants are not supposed to deliver rude surprises. This is where you could step in. With a lot of work, some knowledge of human-factors principles (books on the subject are becoming more widely available), and a little luck, the result will be a polite machine. It will incorporate the cardinal virtues of functionality, robustness, and ease of use. Errors will be hard to make and easy to recover from. And you, the writer, will bask alongside the engineers in the glory of a successful product.
In some fields -- particularly aerospace -- the jobs of ergonomics, "man- rating," and man-in-the-loop design call for specific engineering expertise. There is much at risk in the biomedical field as well; designing safety into the radiation therapy machine mentioned earlier would have been a daunting task for a technical writer (though obviously the engineers didn't do such a good job).
There is college coursework available in human factors, an interdisciplinary field that combines various aspects of engineering with cognitive psychology. If you wish to go into human factors in a field like aerospace or medical technology, with such complex and esoteric problems and so much at stake, you'll probably have to get some formal education. But the computer industry -- software especially -- provides a unique combination of challenge and opportunity.
Just about every facet of describing a process has an exact analogue in designing a process. Think about these aspects of design and how you, as a writer, already deal with something along those lines. They range from the "grand strategy" level to minute "tactics," but all should be familiar.
These are just the large issues. Many similarities are trivial because much of screen design is what you already do every day: using words and graphics to direct action and convey information. Accuracy, page layout, parallelism, and avoidance of ambiguity are just a few of these analogues. A good software writer possesses many of the qualifications for human-factors design.
In a broad sense, the only qualification necessary is willingness to extend one's rhetorical concern for the reader to cover the metalanguage of the man- machine dialog. In practice, some knowledge of both human-factors engineering and technical feasibility is required. (Legal issues are likely to bear upon user-interface design more and more in the wake of several "look and feel" lawsuits filed in the late 1980s, but as of this writing it is too early to say anything concrete about their effect.) Most of the qualifications, however, can be picked up on an ad hoc basis. Certainly one can study human factors and psychology in a degree-granting program, but much of the "rat running" has already been done and need only be applied. There exist a great many references on the subject, some written in general terms, others with reference to computers or even to specific makes and models of computers.[4]
The main requirement is the ability to think analytically while looking at a task from the user's viewpoint. One would hope that the person who must write the instructions can do so.[5]
Making your company realize the importance of user-friendly design is only part of the battle. You still have to convince them that you can and should be involved; some firms, and some managers, take formal job descriptions very seriously. Eloquence and its partner, diplomacy, can help your cause. And the best way to back up eloquence is with concrete, workable suggestions.
Before providing the suggestions, you must become involved at least peripherally with the product team. Inserting yourself "in the loop," as engineers put it, takes some knowledge of the product development cycle. The length and structure of this cycle will vary, depending on corporate culture and type of business. (A company that writes custom mainframe software in response to Requests for Proposal will do things differently from one that develops consumer PC products on speculation, for instance.) But something that most cycles have, in function if not in name, is the Product Requirements Specification. This document lays out the requirements that a product must fulfill, in the opinion of the marketing and engineering staffs, in order to succeed.
If the company is receptive to your involvement, you should become involved in the work leading up to the PRS, because having your say early gives you greater influence with less disruption. If on the other hand you find yourself stymied by corporate structures or traditions, assisting editorially with the PRS is still a good idea; while shouldering some of the burden of producing the document, you might discover a venue for your ideas, or at least gain some credibility. Either way, the writing of the PRS is a watershed event in the course of defining a product and is thus a natural place to get involved.
That having been said, there are a great many factors, many of them beyond your control, that determine whether your comments will be gratefully adopted, considered, or summarily rejected. Here are some pointers.
Again, it helps to make comments early in the development cycle.[6] As the ship date is approached, the burden placed on the engineers by your changes becomes the least of the problems. Large amounts of work by support groups, including training, engineering test, and last but not least documentation, might have to be revised. Knowing the way your company develops products is crucial to selecting an appropriate entry point.
There is also the minor problem that you might not be able to summon up all your best ideas on schedule. But that problem is familiar to writers, programmers, and all creative people for that matter. Perhaps you will get another chance during a major revision cycle.
Once developed, programs generally go through a life cycle of major and minor revisions. Some revisions are strictly bug fixes and there is no opportunity to make further improvements. Others, though, are coordinated with updates to documentation, training materials, and so forth, providing a chance to make significant changes.
Even if you had an opportunity during initial design and didn't take it, don't give up. Get to know the engineers and managers as you wait for a major revision point. Although it will be harder to introduce new ideas at a revision than it would have been to incorporate them in the first place, the ideas themselves are likely to be better, simply because everyone involved (including the customers!) has become familiar with the strengths and weaknesses of the product. The openness of the opportunity depends on the scope of the revision, which is determined by marketing as well as technical concerns.
One of the biggest marketing concerns is the ability of the customers to cope with change. The screen menus of, say, a protocol analyzer can be revised without much difficulty, and the people who use such equipment are well prepared to change their ways. But at the other end of the spectrum, improvements in user friendliness might require the restructuring of a million- record database or the retraining of a thousand key-entry operators. In this kind of environment, changes will not be regarded lightly, even if they would result in major improvements.
When you confront such problems, patience and understanding are in order. Human factors, after all, can be broadly defined as the art and science of coping with people. Add the phrase "for money" and you have an equally broad definition of business. In a business sense, there is more to customer satisfaction than just making keystrokes more intuitive.
Another business problem relates to the earlier point about the impact on other departments. When you suggest changes (at least relatively superficial ones like screen and menu changes), R&D gets off easy. Generally all they have to do is write some code and test it. Other groups have to change printed materials or, worse, change customers' ways of thinking about the software. Such changes cost money. This is why the product life cycle has only a few major revisions. Why go through all that drama over and over when the program manager can save up everybody's comments and put them all in at once?
Technical difficulties also come into play. Some interface suggestions are easy to implement; others are quite difficult. A naive analysis suggests that screen changes are much easier to make than fundamental alterations in the way the product works, and indeed this is generally the case. Sometimes, though, even "simple" changes can have unforeseen ramifications, and may involve factors beyond the sphere of influence of the product being developed.
A personal computer modem, when issued an invalid command, responds with ERROR.This unamplified text gives no clue as to why the command was invalid: was it improperly formatted, did it contain out-of-range parameters, or did it simply not exist? Nor does it reassure the user that the command was rejected harmlessly and that nothing was changed. Furthermore, the cryptic message has been preserved through many generations of modems.
There are two good reasons for its persistence: one intrinsic, one extrinsic. Memory space within a modem was once scarce enough to make every letter precious. This situation is changing, but software that interacts with modems has been written independently by many companies. There is a risk that amplification, even if it preserved the word ERROR, would cause incompatibility. This sort of thing can stymie the best-intended and most welcome efforts at increasing user friendliness.
Human-factors design need not, and should not, be a solo job. Perhaps the seminal idea behind a good human interface will come from one person, that being the nature of things, but as with other aspects of software design, the process of working through the details can involve a good many people.
Searching for the truth in order to place it under house arrest (to borrow the bon mot of science fiction writer Robert Heinlein) is not the goal. The idea is to cooperate -- to make yourself a part of the product team. There are many possible sources of assistance; they include marketing analysts, the technical service personnel who work the phones and make field-support trips, and, of course, any human-factors talent the company might already have. In other words, talk to people, especially the "grease-under-the-fingernails" people. You'll find co-workers who can help design, and who can review and test your work. Perhaps even more importantly, you'll find people who haven't the time or ability to contribute to the design, but who can use their places in the power structure to advance both your cause and that of human factors in general.
One of the underlying assumptions of this essay has been the idea that involvement in human-factors design brings many benefits. Indeed it does, but there are drawbacks as well. Design involvement has deep implications for the product, the documentation, and the writer; not all of them are good.
It is possible that your presence on the design team will not be welcomed. Some companies may not appreciate the importance of human factors. Others might think that you are stepping out of line. (Technical communication is not held in high esteem in some firms, which doesn't help matters.)
True, you must prove that you know what you are talking about. But once you've done that, most programmers will be receptive -- even grateful. Their gratitude, though, may not be immediately apparent. When critiquing a user interface, you are casting aspersions (however diplomatically) upon the quality of someone's work. Think of it in the familiar terms of an author-editor relationship and you will see how to accomplish your goals with minimum trauma.
Chances are that the company will be grateful too, and this can help you later. If you are lobbying for greater status for your profession (as many writers are doing), contributing to product design will serve your interests well.
Writers can have other ulterior motives for getting involved in design. Many are would-be engineers, or engineers seeking a change of pace, or, to be brutally frank, failed engineers. For some, human-factors involvement is a back door into the technical staff, or at least a chance to share the spotlight.
It also provides a gratifying opportunity to make an original contribution. Technical communicators so seldom get to invent anything! Many technical writers and most editors spend their days polishing the work of others rather than doing original work. Human-factors design can be a very satisfying way of contributing to the thing itself.
There are drawbacks as well. One frequently cited reason for staying out of the design process is the risk of losing perspective on the product. Admittedly, a little distance has its advantages. We might think about an analogy between our descriptive business and the similar work that is thought of as "journalism."
Journalists have traditionally prided themselves in objectivity. They consider it to be the cornerstone of truth, knowing in the backs of their minds that true objectivity (as opposed to a faade of it) is very hard to come by. The New Journalism that began evolving in the early 1960s reacted to that tradition by flagrantly spurning the trappings of objectivity. One of the most conspicuous ways of being unobjective was "gonzo" journalism -- participation in the event being covered.
Since technical writers seldom find themselves in the investigatory, adversarial relationship with their subjects that journalism requires, their own credibility and the veracity of their work are not at such great risk. (They are also unlikely to be beaten by a motorcycle gang, as was gonzo journalist Hunter S. Thompson, but that's another story.) But they still have to be careful about a couple of hazards.
There is indeed a risk that you will get too close to the design and lose that important appreciation of what the user needs to know. But you are hardly likely to write a satisfactory manual without an intimate understanding of the product,[7] so you risk losing your perspective anyway. The countermeasures are the same in either case: review by a skilled editor and testing by sample users.
There is also the problem of hitting a moving target. In a typical theoretical product development cycle, the writers are given a more-or-less-frozen specification and go from there. This approach doesn't allow much room for influencing product design, but it has one great advantage: the writers know how the product will "look" and what it will do.
This academically ideal design cycle does not hold up under the deadline pressures and evolving requirements of the real world, so writers often have to shoot at a moving target. Some writers feel that the continued vacillations of the engineering department are bad enough; they are not inclined to add changes of their own. Gonzo technical writers can lose their objectivity just like engineers -- and one of the problems of engineering management is figuring out how and when to wrest the product away from its designers. Writers who contribute to design can contribute to schedule-slips as well; they can even put their own deadlines at risk.
As with all invitations, there is also some requirement to reciprocate. It is awkward to ask the engineers for a chance to edit their product, then refuse them the opportunity to rewrite your manual.
Certainly there is nothing wrong with not becoming involved. Some very good technical writers feel that their time and skills are better devoted to their primary occupation and would rather not dabble in software design. But when the technical team gives them software that could be improved through a few simple measures, how can they resist the temptation to comment?
Another important consideration for the erstwhile kibitzer: you cannot afford to leave your competence or dedication in your own field open to question or neglect any documentation tasks for which you might still be responsible.
Companies in markets where human engineering is critical, and exceptionally aware firms in areas where it is merely desirable, might well hire human-factors specialists. These people tend to be responsible for nothing else; some may even be commissioned by management to do basic research instead of working on marketable products. But things are different if you are a technical communication specialist without the paper qualifications to do human-factors engineering. You are trying to perform an enhanced role, one probably not included in your official job description.
Whatever your own motives for design participation, you must keep one thing in mind: you are basically being paid to write, edit, or illustrate, and you are being paid because the job must be done. Even in a cooperative and permissive company, you can't just go off and "do your own thing;" if your basic official responsibility is documentation, that has to be your first priority. But if you approach human-factors design diplomatically and with an awareness of the limits of your qualifications (whatever those limits may be), few companies will spurn your efforts.
The Laboratory is supported by the U.S. Department of Energy under Contract No. DE-AC03-76SF00098.
Disclaimers and Legal Notices apply
to this document and its uses, and access to and uses of the system on which it resides at
Ernest Orlando Lawrence Berkeley National Laboratory. Like all Web pages, it may be
linked with pages and systems beyond Laboratory jurisdiction. Their
contents and uses are the responsibility of their authors and administrators.
Please visit the Berkeley Lab Home Page.