Using humor in your documentation. Or not.

Tom Johnson wrote a great post about user manuals, and wondered whether a bit of humor would help keep a reader’s attention, and make them more willing to read (and follow) help instructions. I have complex feelings about that, and I’ve been able to argue myself into agreeing and disagreeing with the use of humor in help documentation.

Is the possible benefit of adding humor to documentation worth the cost?

I’ll admit that I don’t use humor in my user documentation. I’ve been writing documentation for enterprise software, and that’s not where you expect your audience to expect to find, or be willing to tolerate, humor. I’ll come back to this, but now I’m wondering: Why not? People using enterprise software are humans, and they’re used to reading large, dry manuals. They’d probably appreciate humor more than anyone else. But…

Writing for translation

I started working for an enterprise software company, in their database tools department. I learned tech writing from senior writers, a couple of whom had learned to program using punch cards. Our documentation was translated into 20-something languages by a team in Ireland. I was taught that every single word cost money. Any extraneous word that a translator had to work on represented an unnecessary cost to the company.

Our style guide had a large section about translation: avoid ambiguous words, drop wordy phrases (“In order to” becomes “To”), do not express your own identity (although this is also to keep our documentation as consistent as possible), and absolutely do not use humor.

Humor doesn’t translate well, if at all. Even to people speaking the same language, humor is subjective. Our readers aren’t looking for jokes in user manuals! Adding humor makes the subject matter seem less serious, and our companies paid serious amounts of money for very serious software that will help them do their (serious) jobs.

In short: No one is looking for The Hitchhiker’s Guide to SQL Databases.

(Although now that I thought of it, I’d read the hell out of that book. Let me just add that to my idea pile…)

So: Humor doesn’t translate, it’s expensive, and you’re probably not that funny, anyway.

I get this argument, and I’ve written this way since I started. I didn’t use humor in my college or high school essays, so it’s been an easy rule for me to follow.

Let me try an example

If I was writing a warning, for example, it would be like this:

icon_important IMPORTANT: Before using this feature, make sure that “Send email to users” is set to No. If it is set to Yes, this procedure will send email to all registered users. You can set “Send email to users” back to Yes after completing this procedure.

That’s a pretty lengthy warning, to be honest. But what about this version:

icon_important IMPORTANT: Before using this feature, make sure that you set “Send email to users” to No, unless you want to spam your entire company and get snarky notes from your coworkers until your boss tells them to knock it off. Once you’ve completed these steps, go back and change “Send email to users” to Yes, and we promise that you won’t get in trouble.

It’s not blatant, pie-in-the-face humor, and it doesn’t change the meaning of the warning. But it is more memorable, and there’s the sense that the writer has seen that happen before, or even lived it. Or at least tested it.

But it’s longer, and might cause your translators (or their software) some headaches (does “snarky” translate well? And what does this mythical boss want to “knock it off” of, exactly?).

Corporate tone and voice

Another consideration is your corporate tone and voice. This is part of your overall corporate content strategy: Is your company serious in all of its communications, or are you going for a hip, SaaS-y dialog with your customers (yes, pun, groan)?

If your company has adopted a very serious, high-minded style (you’re working for a bank, or for a large, established software company), then you have the answer: refrain from using humor, and hew to the corporate style guide. This has been the case with almost all of the companies I’ve worked for. The view of these companies is that humor is not only difficult to translate, it also takes away from the seriousness of the business software. Or at least the user’s perception of it.

But what if your company wants to communicate in an informal way? I’d suggest starting small, and working your way towards a casual tone and a few witty asides. But that assumes that your audience is reading in the sequence that you wrote the docs, and that’s unlikely.

Don’t let humor get in the way

I haven’t seen a style guide that mandates jokes per page, and I’m guessing that I never will. At least not for software documentation. I haven’t seen a lot of humor in documentation, but I’ve seen more that use a casual style, which can include a few amusing bits and pieces.

Similar to the warning example that I attempted earlier, the humor can’t get in the way of the message. Humor can be distracting, but that’s the point: It catches the reader’s attention and makes the instructions (and warnings) more memorable.

But I’ve already admitted that I don’t do it…so what’s my point?

I haven’t used humor in my documentation, so why take any advice from me? Good question! I’m playing devil’s advocate here, and trying to figure out how and why to use humor.

Going back to how I justified humor earlier:

…there’s the sense that the writer has seen that happen before, or even lived it.

Maybe it’s not humor that I’m looking for, but empathy. I want an understanding guide to help me find my way when I’m frustrated; I don’t want a stern authoritarian who knows all of the answers and delivers them in a haughty tone.

Ok, maybe that’s reading too much into the standard, dry writing style that you find in technical writing. But you’d never describe a reference guide as “friendly,” would you? I’ve seen very few, and written even fewer.

Let me be honest: I’ve written none. I’m guilty of the dry, formal style. This blog is a way to help me break out of that.

So: Funny or not?

Right now, the stuff I’m writing isn’t being translated. The only style guide that I have to follow is the one in my head, and those are the rules that I want to bend. I want the docs I write to be friendly, and helpful, and accessible (capital-A Accessible, too, and that’s what I need to reconcile). Friendly help, Helpful help…that’s what I’m betting will be more attractive to readers.

I’m certainly not a comedian, or a comedy writer, but I kinda like that warning example that I created. I’ll just tone it down a little when I next write something like that to use in product documentation. Of course, since I’m a lone tech writer at a startup, I can get away with that.

Unless my very snarky coworkers find it, and my boss tells me to knock it off.

10 thoughts on “Using humor in your documentation. Or not.

  1. Good analysis. Thanks, Neal. I guess my rules for using humor are:
    – Is it audience appropriate?
    – Does it align with the brand image (corporate tone and voice) you want to project?
    – Is it actually funny?
    Only when all three are true, should you even consider using humor in technical documentation. Even then, do so only if you’re sure. So is it ever worth doing? Oh, yeah. ‘Cause when it’s done right, it’s one of life’s true pleasures.

    1. I like those rules. I’ve never hit that trifecta, but I also haven’t put enough effort into it. I’m used to self-editing away any trace of humor or personality, so it’s going to require a lot of practice.

      And since my docs have a comment feature, my readers will be able to point out exactly how terrible my jokes are.

  2. My one brush with “humor” was a new-hire senior writer who put “Arbeit macht frei” in his email sig to customers in Bavaria. He explained it as “Irish black humor”. He didn’t last long.

    1. Thanks! Getting tech writers started on corporate blogging is a great idea. I have seen it done, but it’s still pretty rare. I agree that it would be a great way to allow tech writers to adopt a more casual tone, and as you say it’s an appropriate place for it. Corporate blogs are seen as MarketingLand, so we need to figure out ways to feel comfortable writing in that context…although your marketing team is probably hunting for content, and might be surprisingly receptive. I need to look into this more, myself.

      1. We do corp blogging a lot at Adobe. I don’t know much about other tech giants but it feels counter-intuitive to rarely do it!

        Also, it gives, not just tech writers but everyone on the engineering teams, to get in touch with the real community; interact with the real users; face the real bugs; get to know the real workflows…

        Feel free to drop by on Twitter/email for more brainstorming around this topic. And again, much thanks for this thought-provoking blog post.

  3. My experience is that in a ~1000 page corpus of end-user documentation, a little humor helps keep the reader engaged. Nobody wants to read dead-dull page after page without having a breath of humanity thrown in for flavor. Consequently, for particularly long manuals, if you’re adhering to the ultimate i18n style guide, you’re going to see your users give up on the docs (if they even started), and go try experimenting first. Sometimes (but not usually, if your QA and UX folks are good) with disastrous results.

    1. That’s what I’m looking for: some sense of humanity in the docs. But we as tech writers have been trained to avoid that because it’s not serious, it’s difficult to translate, and it’s difficult to manage across a doc set.

      But now our customers can turn to google and find answers at other sites, maybe where some helpful person has rewritten our docs, added their own examples, and humanized the docs (StackOverflow is a great example).

      I’ll be honest: Even though I’m biased towards reading manuals and help, the sight of a gigantic PDF will send me running to any other option I can find. I’ve written those dead-dull pages, and I guess now I’m looking to atone for my sins.

Comments are closed.