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:
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:
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.