Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

How much humour is effective in technical documentation?

+0
−0

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

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/33524. It is licensed under CC BY-SA 3.0.

0 comment threads

5 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+2
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33528. It is licensed under CC BY-SA 3.0.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33527. It is licensed under CC BY-SA 3.0.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33526. It is licensed under CC BY-SA 3.0.

0 comment threads

Sign up to answer this question »