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)?

  • 11
    When the reactor's on fire, the manual author's bon mots are less of a delight than they were when you took off your jacket because the room seemed a little warm.
    – choster
    Commented Jan 23, 2018 at 20:00
  • Please include a link to your reference. And possibly a quote.
    – Cyn
    Commented Mar 1, 2019 at 5:26

6 Answers 6


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.

  • What about internal use only documentation?
    – tuskiomi
    Commented Jan 23, 2018 at 22:17
  • 2
    @tuskiomi Internally it will often be the same. The user is still in a hurry and in a bad mood for much the same reasons. But internally there is not the same motivation to add things to make the documentation attractive as there is with outside users. Making it funny doesn't really serve any business purpose internally.
    – user16226
    Commented Jan 23, 2018 at 23:14

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.

  • 4
    Agree that localization is a huge concern. It's hard enough to avoid accidental use of idiomatic language - why go out of your way to add more untranslatable content?
    – topicref
    Commented Jan 24, 2018 at 12:50

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.


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.

  • 3
    To improve their penguin research, users who are employees at Microsoft should have been excluded from the sample :P
    – DVK
    Commented Jan 25, 2018 at 15:26

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.

  • I like this answer. But, what do you mean by "use the thesaurus on even word we could ..." Guess it should say every. But do you mean, you used synonyms? Would be cool if you could provide a link. Commented Mar 19, 2019 at 19:58
  • @SybillePeters Thanks for spotting the typo. Unfortunately I don't still have a copy of that report. It was many years and several computers ago. Basically we replaced every normal word with the longest and most uncommon synonym we could.
    – linksassin
    Commented Mar 19, 2019 at 22:46

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.