Chapters 4-7 <You are here
Note: This is a quick conversion of what had been a glued-binding book, to a 3 long HTML files. Over time, I'll improve the conversion. A single PDF (854K) and DOC file (774K) are also available.
The ‘Little Things' that make the difference between good business and bad are only little when you do them. If you don’t do them, they’re very big things.
Despite all of the progress made in making programs friendlier, there is still a great deal of ignorance and indifference about program design. The following excerpt is a typical rationalization from someone who simply lacks the imagination to envision how a program could be as powerful as it is easy to learn.
He just good doesn’t get it. Unfortunately this quote is not from 1980 but from 1995. It’s altogether fitting that it’s from a book on the Internet, the towering inferno of obtuse, opaque, and arcane commands. Today’s best programs, despite being very complex and powerful, are easy to learn and easy to use. Today’s best programmers recognize that the statement above is a relic of days long gone.
The goal of user interface design is to reduce the need for training and documentation to a reasonable level, such as zero.
The user interface must help you cope with the fragile, invisible electronics, the hiding places called disk drives, the unfriendly operating systems, and the incomplete programs described in Chapter 3. The relative success of an interface is determined by the skill and desire of the programmers and the usual business limitations: time and money. Designing user interfaces involves a special area of expertise that has come to be know by the high-falutin’ name of ‘human factors engineering.’
Imagine you’re on an elevator, and as the doors are closing, you hear someone out in hallway, running up to the door saying, “Hold the door.” You hurriedly look at the array of buttons to find the Open Door button. There are two columns of perhaps ten or twenty buttons, perhaps with one row that has “Open Door” and “Close Door” in small letters. Can you find the right one in the two seconds before the door has closed? Sometimes yes, sometimes no.
Now consider if the Open Door button was a large, arrow shaped button, immediately beside the doors, rather than being the same shape as lots of other buttons which are less time-sensitive:
That’s human factors engineering—designing things for the way they are used, and the way we interact with them. In the computer world, 95 percent of the human factors involve communication. And this communication occurs through the user interface.
As programs have evolved from the command prompt systems of the 70’s to the menu systems of the 80’s and the full graphical user interface (GUI) of the 90’s, the significance of the words on the screen has evolved too.
Command prompt systems, with only a C: staring at you, required you to get all of your instructions from documentation or training. You communicated with the computer, but it did almost no communicating with you.
Menu systems provided more words on the screen to guide you. Today’s most advanced systems do everything for you except those tasks that absolutely require a human operator.
Ø The words and images on the screen
Ø The answers that you type on the keyboard
Ø The use of the mouse and the keys on the keyboard
Ø The sounds that the computer or other devices make
Ø The way that the computer responds when you do things
The rest of this chapter will discuss how these elements are used or misused.
A basic tenet of user interface design is that programs must behave very consistently—that shouldn’t come as a surprise. What was a surprise to me, however, was how quickly users become trained to do what the computer teaches them to do... and how blindly they apply it once learned. If you condition people to hit the ESC key to go back to a previous state, they will quickly start hitting ESC to reverse, no matter what.
The machine makes you a machine.
This finding was an interesting by-product of my work with a point-of-sale system. Although our system was head-and-shoulders above our few competitors, our customers' learning difficulties were painfully apparent. The machine made them into automatons, but the user interface didn’t apply the rules uniformly.
A great example involved the method for exiting our menus . The menus on the system were alphabetical menus. That is, they offered A, B, C choices and if the menu had only 2 functions, you exited it by hitting 'C.' If the menu had 4 features, you exited it by hitting 'E' and so on:
A. DO THIS
B. DO THAT
C. DO SOMETHING ELSE
We had perhaps five programmers who had written the programs and used different ways to exit from the specific features that the menus accessed, my favorite being 'HIT 99 TO END' which I vaguely recall we also used in Mrs. Murphy's 11th grade Algebra/computer class, circa 1972.
One day, I told our company president that we really should clean up this mess and make all features end with one technique. I bet him that there must be "20 different exit techniques on our system," to which he remarked that the system needed work but surely there weren't 20! I counted them and was stuck at 19 until I found one that was on a password request and instructed users to ‘Enter EN to END.’ That's right, to get out, you would type E-N followed by the [ENTER] key.
This expectation of consistency is a great thing when everything is designed well and working smoothly. But it means that any serious departures from a consistent interface can become a serious Achilles’ heel.
A postscript to the previous anecdote... When I recommended to the main programmer that all menus end with ‘Z’ irrespective of how many items they had, I was pleasantly surprised to learn that he implemented it in the next release of the software. But when I looked at the new system, I was disappointed to find the same old menus. I asked the programmer why he didn’t do it.
He told me he did make them all exit when the user presses ‘Z’; he just didn’t display the letter Z on the menus! Which brings us to the next subject.
For every computer problem, even hardware problems, there is a corresponding improvement waiting to be done to the design of the software or user interface.
It is not your fault... the problem is not ‘user error!
A common saying about design in general—not just programming—is that 'form follows function,' meaning that a thing becomes what it is because of what it does or how it is used. But in my experience, this is decidedly not true in many manufacturing instances, and computer programming is no exception.
Bad design is often the result of designing things for the convenience of the manufacturing process, rather than the end user. In the example of the elevator’s Open Door button, earlier in this chapter, the button is usually camouflaged among all of the other buttons because that’s the easiest way to manufacture it.
A classic example of this problem is the location of the Print Preview feature in many programs. It’s on the File menu, near Print, instead of on the View menu. In this case ‘form’ has followed the convenience of the programmer, instead of the function expected by the user. These functions are shown on the following menus:
<<<Note April 24, 2004... oops, a few pages got chopped here. Please refer to the PDF or Word versions. Sorry, JB>>>
My candidate for the all-time winner for user interface problems is so pervasive and trivial that it fades into the background. But it’s also obscure because it involves hardware. It’s the way that the Caps Lock feature works on most computers, and specifically, the lost time accounted for, all over the world, as users start entering text in the wrong case. How many times have you done this:
“oNCE UPON A TIME...”
Since I spend a lot of time training other people and diagnosing their problems, I’ve been looking over others’ shoulders for a long time. It’s incredible—but quite understandable—the number of times I’ve seen people start a sentence with the caps lock in the wrong state, and go back and forth trying to get it right. Imagine in a country of 200 million people, how many times this happens every day. Add it up every week, month and year... it’s unfathomable for such a stupid oversight of interface design. It persists because it’s related to the hardware, which is controlled by a few manufacturers.
I don’t expect to instantly prescribe a perfect solution to this problem. This one will require some experimentation and might also require user-configurable options. One potential software-only solution is to change the display background or border color when caps are on. If this were done, even peripheral vision would clue the typist to the current state.
Other possible solutions relate to the key itself; notice that unlike its predecessor on manual typewriters, the Caps key on computers does not stay down when ‘locked’—it offers no tactile feedback. That’s the root cause of the problem. Instead most keyboard manufacturers, following the convenience of the manufacturing process instead of the convenience of the user, place an indicator light on the extreme other side of the keyboards as their only feedback.
The best solution is probably to make the key work the way mechanical ones did, staying depressed when active. Or perhaps the surface angle of the key, or its location should be modified to prevent so many accidental strikes. As I said, this is a difficult problem to simply predict a perfect solution. It requires working things out. Which brings us to the next topic, ongoing design.
While on the topic of keyboards, the answer to the QWERTY typewriter keyboard anagram problem, as near as anyone can tell is “Typewriter!”
A man walked into a computer store to buy a custom-tailored suit. (Bear with me, this is an analogy. If you must, imagine the year is 2010 and you have to go to a computer store no matter what you want to buy.) The salesman took a few measurements, did some clipping with his scissors and sewing with his machine, and immediately wrapped up the new suit. The customer remarked, “Don’t you want me to try it on?” The salesman replied, “Oh, no sir, that’s not how we do things in the computer industry.”
Computer people are starting to acknowledge the importance of usability testing, which means—imagine this—actually trying to see if people can do what they bought your program for. Wow, what a concept! Most of today’s business software, is designed, developed, and sold in a 1-2-3 sequence, a one-way street, if you will. Even good developers don’t routinely expect to involve the users in the design process. If they do, it’s for verbal input, not an actual examination of the system in use.
Funny things happen when you actually work with end users, not just the people buying systems and deciding what they want the program to do. I was installing a system at a drycleaner and was struggling to set up a discount method that the store manager needed. It turns out that when a customer gets clothes altered by the tailor, they can get 30% off on the drycleaning. (A little industry info here: by law, tailors can only work on clean clothes.)
The owner of the store—he recently added this store to his chain—stopped in as we were working on this and inquired what the ordeal was. When I told him we were setting up the dryclean-with-tailor-30% discount, he said “WHAAAAAAT DISCOUNT?” Surprise.
This is starting to change, slowly. Testing labs understand and sell ‘usability.’ The distinction between ease-of-learning and ease-of-using is becoming apparent as the end user community realizes that training costs are a do-or-die business factor. Some systems, even though they are eventually easy to use, take a huge amount of training and indoctrination. With today’s employee turnover, the training impact on usability is crucial, and can be the limiting factor in the successful rollout of a new system.
What can you do?
Whether you are a user, writer, purchaser, manager, or developer, learn more about usability testing. Build usability testing into your written and spoken expectations, particularly your timelines. Watch untrained users try to cope with your program. Don’t tell them what to do; don’t ask or answer too many questions. Just watch and take notes.
Welcome. You’ve arrived at the most important part of the whole book... specific recommendations to improve user interface design and make your software self-training, easily discoverable, and as fun to use as it should be. If you can implement even one of the first five recommendations, you can go a long way toward turning a difficult system into a beneficial one.
This is probably the single greatest piece of advice I have for the entire computer community. One might think that the success of Windows has made it a safe assumption that all, or even most, functions of Windows programs are accessible from menus. But that’s hardly the case, even from the purveyors of Windows itself... even in Windows itself.
With business systems, every one of these instances costs computer companies untold lost time in the support department, as users at all levels, in and out of the company struggle to discover and decipher the new options.
Many of today's programmers got into the field when there was as little as 64K of RAM and fixed-disk storage was 10 MB. This might explain why, when you drop down a menu, the captions are very terse. You might think that each letter was expensive, or that brevity was a virtue for some other reason. Indeed, brevity can be a virtue when a function’s purpose is perfectly apparent, in which case scanning a list of single words is quicker than scanning one of full sentences.
It takes several minutes of experimenting to decode these choices into these verbose descriptions:
Ø Rescale (Stretch/Shrink) Image or Selection
Ø Change Size of Selection Frame
Ø Crop Window Size to Current Selection
This is an admittedly difficult set of functions to describe well in only a few words. But the awkwardness of the terse names is highlighted by the fact that it was hard for me to remember which was which, among the first two items, even after I figured out what they do. Notice in the verbose suggestions that nouns have been added, identifying what the object of the action is.
Even on buttons, there’s no longer any reason to be stingy with words. Spell out exactly what the button does. The following figure shows two buttons, one terse, one verbose, when formatting pictures in Word:
The first button requires you to guess whether the picture will be reset to the previous state or its original state. The second leaves no doubt.
I went up in a friend’s small plane one clear, sunny day for a little jaunt around the neighborhood. We flew into a nearby, uncontrolled airport, which means there is no tower operator. My friend checked the gauges, the situation on the ground and in the air, and everything looked A-OK for landing.
When we descended and got about 200 feet from the ground he acted a little flustered. We landed without a hitch, but it turns out that the ground came up on him about 500 feet too soon, because he momentarily mistook elevation for altitude—a harmless mistake unless you’re piloting an airplane. Fortunately he wasn’t flying by instruments. Splat.
Some wording choices are not as easily made as in the previous story. Often there are two points of view, and there are some good reasons why the words used in the user interface could be one way or the other. But sometimes wrong is wrong.
One day my computer’s power got interrupted, or perhaps the system locked up for some inexplicable reason—I really don’t remember. Upon restarting my word processor, its automatic, timed backup feature tried to help me out: it reloaded the file that I was editing, and prompted me to save it. I subsequently found that I lost the last half-hour’s work, even though I saved my work a minute before the power loss. Can you figure out this little glitch? Answer later.
When computer programs are made, many new functions are created and must be named. In naming these functions, I've noticed that there almost always seems to be a choice to be made between a descriptive phrase that spells out the purpose of the function, and a sort of shorthand nickname. I think that programmers have felt an obligation to name their features, rather than just describe them. The nicknames are almost always a disservice. Here are some examples:
Ø An imaging system has two different functions for attaching editors' comments to a scanned image. They are Notes (one per document) and Annotations (one or more per page). The user has to investigate the difference, then try to remember which is which. Instead, they could simply have been named Document Annotations, and Page Annotations.
Ø At the bottom of the File menu on many programs, the most recently saved files are listed, for convenient re-opening. In an INI file, this list was identified as the ‘Pick List.’ A more explicit name would be the Recently-Saved File List, eliminating the need for documentation explaining what a Pick list is.
Ø Even some of what is otherwise considered progress in Windows standardization has had a negative effect on programmers' understanding of explicitness. Recently I encountered two programs that had dialog boxes with these options:
These are actually very good, explicit buttons, but they were criticized by programmers who have become accustomed to presenting only the standard (but implicit) options, OK and Cancel. This is because, in addition to the belief that standardization is better, it is usually less work for the programmer to use the built-in OK/Cancel choices.
#6: Provide a Master Menu, Integrating All features
With many computer systems, once the system is rolled out, programmers add features as they see fit, wherever they want, often adding new, independent sets of menus. This is where the user-friendliness of many systems starts to unravel. Even if the additional features are appropriately accessed from their own independent menu, a master menu for administrators should tie all of the parts together.
Often, the rationale for making the new features separate is that they are “not appropriate for most users.” But this protectionist logic is misplaced. If the features are sensitive or dangerous in some way, they should be protected by a password, not by being isolated or inaccessible.
Another prominent example is the arrangement of the main menus on the Macintosh. The menu that controls all of the current tasks is on the extreme right side of the top menu bar. The tasks as a whole are more general than the currently active program, so this menu should be the leftmost.
#11: Always Show the Level at Which Options Are Invoked
Ø All sessions and documents
Ø The current session
Ø The current window
Ø All templates
Ø The current template
Ø All documents
Ø The current document
Ø All Microsoft Office programs (yes, some Word options such as spelling even affect other programs)
And, when you consider other programs, the following levels add to the confusion:
Ø Power on/off.... and ROM BIOS restart
Ø Operating system restart (DOS)
Ø Hardware/software drivers that control your monitor, sound card, and so on
Ø Windows restart
A great deal of wasted time could be prevented by clarifying which level every option is associated with, and when the option is invoked if you select a new setting. Usually the level implies the time at which the setting is invoked, but not always. For instance, if you change your Windows screen colors, you do not have to restart Windows; on the other hand, if you change your screen colors from 16 to 256 you must restart.
Indicating the levels at which options are invoked is not sophisticated work. They can easily be indicated by providing words directly on the screen, grouping the options according to level, or explicitly describing the levels in context-sensitive help.
Dynamic menus change as features become applicable. Some programs also change the appearance of items on dialog boxes, an equally offensive practice, depending on the extent to which the items change. For instance, in Microsoft Word, the Tools/Option/View dialog displays an item called Style Area Width, but not in Page Layout view. In this case the item disappears, leaving the user disoriented, until you start poking around to find out why it has changed. In this example, perhaps the reason seems obvious; at other times it might not be.
#14: Default to Saving Work
Trace: Detailed View of Program Commands
Another measure that is needed to minimize the time that is lost to troubleshooting is to enable full logging of processing status that could report on every command in a program. Although the most detailed information would only be useful to experts, it would at least put the user community in the driver’s seat. The current predicament often spells nothing but dead ends and unrecoverable lost time.
;;; Setup Log File Opened 05/17/96 18:36:45
User Name: jack bellis
Install Type: Normal
Source Path: F:\
Destination Path: E:\COREL50
 Using Windows VER.DLL to copy file: 'F:\CONFIG\CORELDRW.REG', to:
;;; Setup Log File Closed 05/17/96 19:10:50''
We need this type logging to be uniformly and easily available. And it must be configurable to let you choose how much detail to track, even including processing that is not regarded by the program as erroneous. Then we would have a chance of working around even problems that the program creators did not anticipate.
A typical situation that would be improved by a detailed trace occurred to me and a co-worker recently. We were trying to use a utility program and got a vague error message saying that a file couldn’t be found. A lot of trial-and-error investigation proved that the file was quite ‘findable,’ but it couldn’t be loaded because of memory limitations (actually the Windows ‘resource’ limitation). While better error messages might have helped in this situation, there are simply too many similar but unpredictable situations to base a solution on improved messages alone. We need a systematic solution.
A somewhat more proactive measure is described next, Layer Accountability.
What can you do?
Programmers: make your program support configurable, exhaustive logging, with an openly accessible
Programming Managers: make a single programmer responsible for an error trapping methodology and managing its implementation by all programmers. Put it in your library.
Ø Draw programs use lines and filled patterns, which the programmers implement with mathematical equations.
Ø Paint programs, on the other hand, use dots of color, as if you were filling in graph paper with a paint-by-numbers technique.
Both have special advantages. We are only recently seeing programs which enable you to get the advantages of both; previously, users had to use one technique or the other. Another example is multimedia authoring programs. Some use a frame-at-a-time metaphor, others use timelines, and still others use a diagramming technique. It’s time to stop making users choose between valuable but mutually exclusive methods.
Stubbornness does have its helpful features.
You always know what you are going to be thinking tomorrow.
— Glen Beaman.
It’s no longer easy to tell where a good program ends and the online help begins. This is a good thing and I guarantee you that it will be even harder as time goes on. As programs continue to do more and more of the tasks that we used to think only we could do, we will eventually find out just how little documentation you really need to read, to learn to use even a powerful program. This minimum amount of text will be in helpful panels that appear as a function of either the program or its training mode.
These trends are already well underway, demonstrated by intro panels that can be disabled after you read them, and wizards that guide you through major procedures. As more of the procedural information is converted to these sort of user interface techniques, I predict that the only substantial need for considerable text will be introductory concepts and troubleshooting. More on that later. Now let’s look at a breakdown of where Help has been going for the last 15 years.
That’s right, none. You’ve seen it plenty of times, so I thought I’d mention it as a tribute to those who’ve given you no help. They deserve it. And it provides a starting point. Let’s get fancy and call it a baseline.
Online or not, a bad book is better than none, if only for moral support. At least someone can say they tried. Bad books repeat what is on the screen and make the information accessible only in the order of the system, with the same words the program’s authors use. Here’s a nice example of a circular reference in—of all things—the online help from a Help authoring tool. Try to figure out what a hidden link is:
Let me see if I understand this now... I should check the Make Hidden Links option if I want to create hidden links. Wow, thanks. (What, you may wonder, is a hidden link? One that is not underlined as links generally are.)
Another example: using a word-protesting—er, I mean word-processing—program, I searched the literature for information on ‘hotkeys,’ ‘function keys,’ ‘keyboard,’ and ‘accelerator keys.’ But the documentation only listed it under the term ‘shortcut keys.’ Well, excuuuuuuuse me. Or consider another word processor where I searched for ‘right justified,’ ‘justified,’ ‘right aligned,’ and ‘aligned right’ but the authors only indexed it as ‘flush right.’ Bad, very bad.
Good books answer the questions why and why not. For example: I installed a video capture board—that’s video, not audio—that came with a microphone input and speaker output connector, but nowhere in the books did it explain what they were for or how to use them.
On this count, genuine congratulations to Lotus Screencam’s writers for actually including an explicit statement clarifying something that cannot be done. They noted that “you can't add captions to a movie that has already been recorded, you must do so while recording, or re-record the movie.”
Good books give you all of the information, rather than trying to protect you; protection is the job of passwords, not documentation. Good books have sections organized for reading in order, like a textbook, going from one concept to its siblings and offsprings. When other orders are helpful, they use indexes and tables to let you access the information in those orders.
Take the information in a good book and put it in a context sensitive help file, and you’ve got the next level. Context sensitivity adds an element of convenience that makes electronic documentation so much easier to use than printed books that what might have been a good—but unused—book might get used quite often.
With a little collaboration between the help author and programmers, cue cards can also be supplied that actually launch functions in the program, and work back-and-forth between the help system and application. Perhaps you’ve seen some systems like this where you click on buttons within the help to perform the steps in a procedure.
Better books have not just the basic information but all the bells-and-whistles that make the book easier and more encouraging to read: graphics, liberal examples, nuances of operation, what-if questions, complete business scenarios, and good trouble-shooting information. Adding this richness of truly valuable content takes perhaps three times the effort and requires significant input from the end user world. If you’re waiting for some sort of ‘business case’ to justify this sort of effort, don’t hold your breath; in my experience, this type of virtue must be its own reward.
Good programs communicate. No amount of add-on information, whether printed or online, is a substitute for embedding the instructions right in the interface.
Good programming has verbose text that doesn’t get in the way, configurable labeling for icons, balloon help, introductory help for procedures, status bar elaboration of selections, a menu system that doesn’t act like a chameleon, complete feedback and logging, meaningful error messages, and so on, and so on.
9. Wizards: Step-Through Dialogs
Hardware’s the fun part. In fact there are very few hardware solutions, only funny stories.
I used to sell my own computer program, dragging around an Atari 800 with a separate floppy disk drive and a 5-inch TV, in a suitcase the size of a small refrigerator. One time I did a ‘cold call’ at a small business that sold car phones—real future-tech at the time— about 1984.
After telling the prospective customer why he couldn’t possibly live another day without my program, I proceeded to open the refrigerator and put on my dog-and-pony show. When I threw the switch on that lightning-fast 3 megahertz Atari, on came a basketball game (not a bad game by the way). It was a cartridge that I had left in the machine by mistake. I had left my Basic language cartridge at home on my desk, making a demo impossible. Arrghhhh.
The customer, however, agreed to buy my program sight-unseen! This was mostly because he was just a modern sort of guy, what the marketing weenies call an ‘early adapter’ (or is it adapter?), but also due to my silver-tongued salesmanship, no doubt.
IO Port 2AD6
IO Port 220
IO Port 240
IO Port 260
IO Port 280
IO Port 300
IO Port ...
Some of these settings can be retrieved from the system, but only when everything is working perfectly. Others such as the port addresses and interrupt settings need to be written down because there are a limited number of them available and you must not assign the same one twice; since no feature of Windows 3.1 (or older) handles the task of allocating them, you always need to be able to see them at-a-glance on paper to assure that they don’t overlap with one another.
Fun ny Story Number Three. I installed
a system at a drycleaner, in Puerto Rico—the first time that I installed a
new style of keyboard that my company had just developed. I couldn’t get
the new keyboard to work so I called ‘the hardware guys’ back home, who asked
if I tried the little switch on the bottom of the keyboard.
I immediately reached under the keyboard and flipped the little switch, at which point the screen went blank, the computer power stopped, and the fan whirred to a stop.
Sweat started pouring out of my face in buckets—bear in mind the average temperature in a Puerto Rican drycleaner is 150 degrees, even without system meltdown. Yes, I had fried the system.
Meanwhile, the hardware guys are on the phone saying “You’re not supposed to do that with the power on! Didn’t you read the label on the bottom of the keyboard?” Duh gee, you don’t say. I asked that in the future they consider putting the label physically on top of the switch, so that one must remove the label before ruining the system.
I spent the rest of the day driving frantically around Puerto Rico—did you know that they drive right off the side of the highway on the grass to make a new lane wherever they want to—looking for a special fuse. I actually soldered leads to the mother board to circumvent the existing fuse, and installed a removable fuse on the back panel. Another victory for Rube Goldberg, if your parents ever told you who he was.
What can you do?
Label it, write it down, put it in your log book, keep it in your files. For advanced PC users keep a single chart of your ‘interrupt’ (IRQ) and port settings, drive specs, and every
For several years now, computer industry experts have been wondering aloud what it will take to make computers as prevalent—and useful—in the household as other appliances. Even if the technology continues along its unfriendly way, there is little question that the sheer numbers will match other appliances soon, as more and more computer-age individuals bring their work home and computer games gain ground. But the notion of making computers a fixture of routine, day-to-day home life seems to be eluding the industry.
The answer is not entirely mystical, however. In
Ø A PC-compatible laptop...
Ø that snaps in and out of a wall-mounted docking base...
Ø probably in or near your kitchen, but that’s your problem...
Ø with a modular, but otherwise common telephone that works whether the computer is there or not...
Ø ready-to-go Internet software, voice mail, modem, and fax...
Ø home banking and finance software, pre-loaded...
Ø modular, stacking add-on units below the keyboard/screen using the architecture that I described earlier in this chapter, so the modules can be replaced without a screwdriver...
Ø for, among other options, a continuous-roll-fed printer, (or any other printer, since it’s a regular PC).
Ø That’s it.
I’m a technical writer and I’m embarrassed. As a group, we’re not part of the solution—we’re part of the problem. The following example epitomizes the often laughable ‘state of the art’ in software documentation. It is an excerpt from the training manual for a data entry system, showing the content of an entire page:
¨ If you have a problem with the system, follow the correct procedure.
Gosh, I wish I’d read this pearl of documentation in 1982—imagine the lost time I would have saved with all of my software problems.
Long before computer books were lambasted for their low quality, most other instruction manuals were the universal object of derision. How many comedians have poked fun at the Christmas tradition of struggling with the assembly instructions for Johnny's new bicycle? If the situation was funny with bicycles, it is infuriating with computers. And the newest trend—to eliminate the books altogether—and provide only the online equivalent threatens to take a bad situation and simply turn it into a moving target, rather than nailing it down and killing it.
Computer books stink because they are a low priority—an afterthought—to many companies. Often the writers contribute to the low quality by falling into the same general syndrome as the technologists: they concern themselves more with their craft than the ultimate value of their product and the outcome that the books must achieve. In other words, they work on punctuation, grammar, nifty new methods, perfectionism, editorial dogmas, and stylistic issues ad nauseum. They do this because it’s easier and usually more fun than providing real information. The result is that the books often look good but don’t really have the information you need. Well, folks, I have news for you:
want good technical writing,
they want answers!!!
“Frame anchors are always attached (anchored) to a paragraph and the anchor is displayed in the left margin of the page. Anchors always move with the paragraph mark as text is inserted or deleted, or when the paragraph mark itself is cut and pasted elsewhere. When you lock the anchor, it prevents you from dragging the frame itself to a different page than the one where its anchored paragraph mark currently is. It also prevents you from dragging the frame’s anchor (an alternate way to move the frame) to a different paragraph. By preventing both of these actions, you can ensure, for instance, that a frame containing a picture will always be on the same page as its referencing text...”
Whew! The reason this option requires such an elaborate explanation is that the program, MS Word, is just is not well suited to page layout. It is a paragraph-oriented program, so explaining something that should be easy isn’t. But explaining difficult functions is the only reason to bother with tech writing in the first place. Users want and need to have the gaping holes in the design of the computer program filled in by unvarnished information. They want to know the things that the program doesn’t tell them. And they want to know how to fix the damn thing when it breaks.
Establishing valuable information is hard work.
The degree of difficulty is directly proportional
to its value.
This is the fundamental issue facing software documentation—the value of information. Sometimes, value is established by providing an intense level of detail. At other times, it is established by better choosing which information to zero in on. And, as programs have become more friendly, value can even be increased by making shorter documentation. More on that later.
What can you do?
Writers: spend your time writing about the things that you can’t discover directly from the user interface: startup concepts, non-intuitive and incomplete things, and problems.
Documentation department leaders: revolutionize your direction. Stop documenting everything. Isolate and target the genuinely valuable issues.
If you've ever read a computer book and doubted whether the writer ever used the program, your suspicion might have been right. With business software, there's a 50-50 chance that the words were written without ever using the feature in question, perhaps without ever using any part of the program. That's because some books are written from 'specs.' Specifications are the documents that tell the programmer what she must make the program do.
Companies often use three kinds of specs: requirements specs from the marketing department describe the features that they would like to sell; functional specs from the engineering department establish which of those functions will be implemented, and how; and then the programmers might respond with a design spec, describing in detail how they expect to program the functions.
With programs from the 60’s and 70’s, where there was very little instruction on the screen, even the sugar-coated information in the specs was potentially valuable to users, so writing from specs was reasonable. With today’s programs, where most of the spec information is on the screen, writing from specs creates useless books that simply repeat the words already on the screen. Who needs that...talk about a prescription for failure! The only thing that is sometimes in the specs, but not on the screen is how the business processes relate to the program. Too often, however, this information is lost between the customer and the sales force.
What can you do?
Writers: write from interaction with customers, experimentation, and experience, not from written promises. If your company tells you to document, from specs, an application that you can’t document by using, use all of your persuasive resources to convince the powers-that-be that it is a poor use of the company’s money and not the most profitable way to serve your customers.
Just like programs, computer books can benefit from being tested. Instead, most companies pour their time and money into proofreaders who critique the spelling, grammar, and technical accuracy, not the usefulness of the information.
When I worked at a big company, I had a very knowledgeable editor proofreading my work, and I learned a lot about some style and grammar issues. I specifically remember learning to use ‘might’ instead of the more common ‘may’ when the issue was likelihood, not permission. (“You may perform function A or B. You might find function B more useful in long procedures.”) There are very few instances in software documentation where ‘may’ is appropriate. I finally got it drilled into my head when I was corrected a thousand times.
Then I moved to a small company where the owner proofread my work. He ‘corrected’ every might to may.
Traditional proofreading is great stuff, but not if it displaces time and money that might (may?) be spent proving that the information in the books is what users need, and that users can find it. Why is more effort put into proofreading? Because it’s easier!
No amount of traditional prufreeding
seems to attain even the superficial goal of aesthetic perfection, so you
should not allocate resources to it, resources that could be used instead
Ø Perpetual chores should be changed into pre-built functionality. For example, when you are instructed to always set up a user named 'Administrator,' the program should do this for you.
Ø Documented workarounds and contrivances should be changed into menu-supported features. For example, with a notoriously lambasted publishing program, to make white text on a black background, you had to make a black line above the text, and then adjust the thickness of the line and set its vertical alignment to a negative number. The manual had a great formula to establish the alignment value:
...approximately one half the sum of the ruling line overall height plus the font size...
How could any book with stuff like this ever expect to get regarded as good documentation, when it’s trying to do exactly the sort of job that a computer program should be doing? That it took them so long to roll this documentation back into the product (I'm assuming they have) literally cost an otherwise awesome product its market supremacy—it was gobbled up by another company as it was swamped with bad reviews.
What can you do?
Writers: diplomatically recommend to your engineers that certain procedures might be good candidates for code on the next go round. (Don’t ask me for help on the diplomacy part.)
Is that really the question? On my three most recent technical writing projects, all of which documented Windows business software, the question has arisen, "Which portion of the product information should be printed and which should be online?" This is a big issue these days in documentation, as companies look for ways to cut costs. In this section I will propose a strategy to provide the best product at the lowest cost.
The issue is not whether paper books are better than online help. Both have their strengths. But the higher cost of printing has forced many companies to transfer the burden of printing to the customer. A hidden factor in this high cost is the practice that has developed over time, of providing verbiage about every single feature of a program. The backlash is the increasing trend to print little or nothing.
Rather than resorting to minimization, however, manufacturers should be seeking the strategy that takes the greatest advantage of both methods. The most win-win view of the issue then is this: "Of all the information about the product, which portion provides the maximum benefit for the manufacturer to offer as a high-quality, printed document?" The answer starts with an examination of the key strengths of the two methods.
When you must read more than a few sentences, printed paper is easier to read than a computer monitor. When the amount becomes more than a few minutes of reading, the advantage of paper becomes even stronger, since you can take paper wherever you go and read it when you have time.
Electronic documentation, on the other hand, can provide instantaneous access to relevant information. Another distinguishing strength of online info is that, wherever there’s a computer, there’s access to information. Many other factors distinguish the two methods, but it all boils down to this: for reading, paper is better; for reference information, good online help is far more powerful than paper.
The first part of my recommendation is that your electronic media should include every bit of the product information. It should contain your getting started information, tutorials, guides, reference books and cards, marketing info, and troubleshooting. Obtaining information costs everyone a huge amount of money—failing to make it accessible is bad business. If some of the information is sensitive, protect it or the system to which it refers with passwords, but don't solve the problem by minimizing its distribution.
The second part of my recommendation is to print an introductory book of up to 75 pages, with the highest possible quality. I suggest 75 pages as the maximum because that's the most that any reader is ever likely to read in a continuous effort, even over the course of a few days. This is based on my own surveying of computer users, and my own experience. I’ve never found anyone who has read the greater part of any user guide.
Microsoft’s innovative approach—don’t laugh—is to make the pages thinner. The book above would be about 250 pages. Their other options were to print increasingly thicker books, split the topics into more volumes, or make the systems themselves transfer the knowledge, by using verbose menus, more wizards, and many of the other techniques I’ve covered.
The most important information in a read-through is a conceptual introduction to your system, information that is key to understanding the way the system is meant to be used, often called theory of operation. Alternatively you might say that this section describes how your business processes map to the computer system. A read-through also should describe the major features of the system and generalizations about their use, particularly concepts that might be counter-intuitive. Remember, the whole point is that this book can be read in a sitting.
Another type of information that is important to put in front of all users, rather than wait for them to seek it out has to do with ‘technique.’ For instance, I did a lot of sound editing recently. It took me a long time to realize that the efficiency of the cut-and-paste process was dramatically affected by the zoom level (how many ‘words’ of sound you see on the screen at once). Although there is certainly no ‘requirement’ that you zoom to a specific level, the experienced user eventually establishes a technique of adjusting the zoom level so that selections can be made accurately and with little wasted effort. Although this type of information is sometimes presented under the offensive term ‘tips and tricks’—implying it is in some way extraneous—it is often vital getting-started information. In the sound editing program, zooming efficiently was vital.
The read-through that I am suggesting is different than the minimal documentation that some packages now ship as a getting started booklet; in my experience, those booklets rarely discuss vital concepts or implementation considerations. Let's look at some examples of the type of information that should be in printed read-throughs:
Ø Microsoft Word stores its paragraph formatting information in the marks at the end of paragraphs. Every new user must be told this information. A read-through is the ideal vehicle.
Ø Corel Photopaint has great features called objects and masks—features that I need to use and which are central to its design—but whose use is unlike any of the simple bitmap editors I’ve used. An overview of the design premise must be accessible without wading through all of the reference information, as I had to do with the online help.
Ø A system for managing railroad cars represents the physical world in carefully-structured layers of data, on which your entire understanding of the system is based. There are locations, facilities, junctions, segments, routes, and so on. The design of such a scheme must be put in front of every user’s eyes.
An imaging system on which I worked had 17 books. For such a large system I would print a read-through for each key user: business manager, administrator, clerk, and integration programmer. This still achieves my goal of giving each user an amount that they can read in a sitting.
By segregating the key information in short read-throughs, and providing all information online, technical writers can provide the best, readable, documentation and get the best value for the printing dollar.
With large, complex systems, users must exert a tremendous amount of effort to learn all of the necessary information. Video training, computer-based training, and interactive multimedia can all play a role in this transfer of knowledge. The important difference between these tools and their primary alternatives, books and person-to-person training, is that multimedia does not require the user to do as much work—the demand on the user shifts from active to passive.
Consider the imaging system that I helped document, with its 21 books of 100-200 pages each. Is it any wonder that no administrator ever became a bonafide trouble-shooter? It took too much work, too much active effort. Of course it was a UNIX system, so there were also some fatalities before the learning process ever had a chance.
I wish I could tell you that I’ve had some good experiences with video or multimedia substitutes for text documentation. Unfortunately, my only experience with videos has been intro tapes that have been painfully basic, to the point that the viewer was assumed to be a moron. Almost every tape I’ve seen starts off saying something like “We won’t try to teach you Windows on this tape...” and then proceeds to tell you one Windows technique after another. Video is a tremendous tool and I can’t wait until it starts being properly used.
I’ve started to see some improvement with multimedia and other tutorial methods that require less active effort from users. I’m confident that this will be an improving trend that is only now beginning to gain momentum and acceptance as authors become more skilled with it.
The most valuable of all talents is that of never using
when one will do.