How much humour is effective in technical documentation?

Question

It's well known that live presenters are often advised to add a dose of humour in order to engage the audience better.

However, I very rarely see humour in written technical documentation; this despite it also being widely known that most people rarely engage with documentation, and consume it very ineffectively when they do.

"The Feynman Lectures on Physics" are a good example of humour being included. Is avoiding humour just a cultural tradition, or is there research indicating that there's no engagement boost from using it in written documentation? (Or, as I would hope, is there research that there is such a boost)?

Answer 1

The typical user of technical communication is in a hurry and in a bad mood. They were working along trying to get a job done so they could go home and have supper with the kids then something broke or refused to work the way they thought it should, or a part would not go on properly, or a bug appeared out of nowhere, or the whole system quit working and blue smoke started pouring out.

They are not in the mood for a joke.

We should think of technical communication like a pitstop. It is a time to get the user what they need to continue as efficiently and with as little drama as possible. There is no time in a pitstop to tell the one about the dentist and farmer's daughter.

That is why there is no humor in most technical communication and why there should not be.

Humor in learning materials is another matter. Some like it. Some despise it. If you are selling a Dummies book, you can appeal just to those who like it and let the people who don't buy an O'Reilly book. But if this is your corporate training, you probably do not want to turn off half your audience.

Answer 2

The Microsoft Manual of Style puts it well:

Don’t try to be funny. Jokes, slang, and sarcasm are context-specific and hard to translate and localize. What’s funny to you might offend or alienate some portion of your audience, so it’s best to avoid these rhetorical approaches.

The Dummies books are an exception to the rule, but people who buy them are a self-selecting audience.

Answer 3

Humor implies an intimacy and casualness that's typically not appropriate for technical communications. Whether it's a tense bug-fix or something-broke-on-me situation like Mark Baker describes, an instructional document being used in a business or professional setting, or whatever else, in most cases it's just improper to presume a particular level of familiarity with a reader.

Besides: what if they think the joke is terrible? (Or worse: offensive?) You're far more likely to lose the goodwill of a reader who doesn't like the humor, than you are to gain lots of goodwill from a reader who does.

Most of the time, humor just gets in the way.

Answer 4

The general rule in tech comm is to avoid humor, and I think the main points of consideration are: audience, context, and localization - if you're considering this at all.

Speaking specifically about the localization concern, the translation of idiomatic language is an important consideration, but another significant concern is cultural interpretations of your humor.

I saw as interesting presentation at LavaCon last year where Jon Ann Lindsey, a Content Strategist from Google, spoke about their own attempts and research on this.

In synopsis: Google encourages their staff to be "Googly" and they did a large case study where they had focus groups from something like 40 different countries look at their documentation and actually had someone sit down with these groups in person to get feedback. They found that even the most minor humorous references (for example a picture of a cute penguin from their image library that was used in their documentation of the same) came across poorly in many regions. Some of this was unfamiliarity because people from some countries may have never seen a penguin. Others found it just plain infuriating and inappropriate that someone would try to insert "humor" or "cuteness" where they were trying to get technical information.

My major takeaway from this was: know your audience. If you're localizing content, this is even more difficult and imperative. Unfortunately, many of us don't have the same resources that Google does to conduct this type of research on a global scale, so it's probably best to stay in the realm of the cut and dry.

Answer 5

It depends on the audience

Personally I feel that technical writing is far too dry. However as an engineer I've done plenty of it. I always try to add humour and levity to make it more enjoyable. This has had varying results.

Here is an example where I went overboard on the levity and it was well received. For a physics report my partner and I decided to use the thesaurus on every word we could without changing the meaning, replacing common words with their most obscure and convoluted synonym. The report is the most ridiculous and over the top word babble I have ever written, but it is technically correct. We received full marks and a slap on the wrist for 'cheek'.

Another time when writing my final year project report I was working on the 'why this project' section. The project was about a vision guided landing system for autonomous drones and we thought it would be appropriate to put the top reason as 'drones are cool'. This didn't go down well, we lost marks for being 'unprofessional'.

Unfortunately I have yet to understand how to tell the first audience from the second. Sometimes readers will appreciate it and sometimes they will crucify you for it. It's up to you to judge your audience and if you can get away with it. If you think you won't get in trouble for, please do it. The world of technical writing could use a little more levity.

Answer 6

I recently had to oversee the introduction of a custom-built IT system in an industrial environment. A few in-jokes in the manual went over quite well during training. They were along the lines of using the name of a known computer-illiterate person to illustrate log-in or listing example orders that are impossible to carry out for non-obvious reasons.

However, in this example, 1) the humor was completely tangential to the technical message, no words were spent on it, 2) it was subtle to the point of deniability, 3) it was specific to the audience - letting them feel clever for getting the references.

Under such circumstances, I've seen such subtle humor to work. Otherwise, there's no room in technical documentation for it. It's better to provide brevity. In my experience, the problem with tech writing isn't the lack of humor, but the excess of repetitive formalities and passive voice.