The role of humor in documentation - or - laughing 'til it bytes - technical writing

Communication World,  Nov, 1991  by Peaco Todd

• E-mail
• Print
• Link

Pity the poor tech writer. We have been called many things by readers immersed in the murky waters of the typical computer software manual, but fascinating isn't likely to be one of them. To counter this prejudice of tedium that most people seem to assume is the essence of technical writing, we have been positively shameless in the attempt to enliven our art. We appeal to their senses as well as their intellects. We plan copious white space, and direct them hither and yon with cunning mauve arrows. We deck our paragraphs with icons so that everyone can follow the thought. All of these devices are worthy, and have contributed to documentation becoming more accessible, readable and effective prose. Yet, despite these efforts and improvements, software documentation maintains the most devastating reputation: that of utter dreariness.

Why is that? Why in order to learn anything from software documentation does one need the attention span of a sphinx? Concurrently, why is it that any lengthy exposure to a user guide is practically guaranteed to reduce the reader to the mental state of an artichoke? In other words, why is documentation so boring?

Why does it seem to be so internally difficult to make technical manuals both informative and interesting? The problem is engineered One reason surely is that writers and designers face problems that up to now have been generally ignored. Among obstacles too numerous to catalogue, the primary difficulty may be that most software is designed by engineers. Self-evident, but contrary to assumption, engineers are not human. They belong to a sub-species, Homo Obscuro. It has been discovered that they comprehend the world differently from regular people. To demonstrate this problem, Prof John Wyatt, of MIT's Department of Electrical Engineering and Computer Science, has systemized what a typical engineer might think were some good rules for user documentation:

Rule 1. No one learns by doing.

Rule 2. Think like a machine: Do everything in binary.

Rule 3. Anybody who wants to know anything wants to know everything in equal detail.

Rule 4. No one ever wants to do just a few simple things with software.

Rule 5. If the reader is not familiar with all previous generations of the product in intimate detail, he or she has no business reading the manual.

Rule 6. An underdeveloped strategy for documentation is the use of accusations and threats.

Rule 7. Plain-language descriptions are always insufficiently precise.

Rule 8. Any user-oriented computer language is merely a tool to obscure the real action going on at machine code level.

Rule 9. You might think that manuals exist to inform the user. You're wrong. The real purpose of the manual is to record the design history of the software for the engineers. So, for each feature you should include a detailed account of all competing features which were rejected in the final design review.

The fact is, documentation, like the engineer, deals with something that has one essential mandate: to work. However, often that seriousness of purpose translates to a heaviness of approach. What's so funny? A friend recently remarked that most of the humor presently found in technical documentation is entirely accidental. However, the deliberate use of humor by technical writers can add immeasurably to the effectiveness of material whose only real purpose is not to be savored, but to serve.

Perhaps a primary point to consider is just exactly what is humor? E.B. White said, "Analyzing humor is like dissecting a frog. Few people are interested and the frog dies of it."

Also, what may be utterly hilarious (or even mildly amusing) to one person may be inexplicable or even offensive to another. The global community has become both increasingly diversified and interconnected. Nevertheless, different cultures answer the question 'What's funny?' in radically different ways.

A few years ago I was teaching a class in cartooning at MIT to a group of graduate students and visiting scientists. Since eight Asian and European nationalities were represented, my initial exercise was to find out what students found funny.

I brought Gary Larson cartoons to class. Although the different cartoons elicited various responses, in general everybody was amused, except for a visiting scientist from Osaka. He just didn't find the material humorous, and he decided it was because he was Japanese.

I asked him to describe a situation that people in Japan would find funny. He mulled it over for a minute and then said, "A funny scene would be a group of pedestrians at a stop light, and even though the light was red, the whole group was crossing the street anyway!"

None of the rest of us in the class considered the anecdote a knee-slapper, but we understood what he meant. His example also illustrates that while "funniness" has a definite cultural component, the urge to perceive and respond to humor is universally human.

Humor is the bounding of things by extremes. Nevertheless, those extremes must be carefully drawn. One critical element of the effectiveness of humor is appropriateness, both of context and' intent.