Does Humor Belong in Technical Writing?

A serious analysis of the issue.

Frank Zappa titled his 1984 live album "Does Humor Belong in Music?". The answer, for anyone who’s a fan of Zappa, is “yes, of course.” If Zappa isn’t your cup of tea, perhaps you’d answer “yes, but not that kind of humor.” Regardless of whether you enjoy xylophones and long guitar solos interspersed with sarcasm and satire, most people would agree that humor is an essential element of music, just as it is with fiction, television, or theater.

When it comes to technical and reference books, however, humor may seem like a stretch or out of place. The reader of a book about algebra gains nothing if the author jokes about politicians and current cultural trends between the algorithms. It’s likely that those jokes wouldn’t even make it past the editing process.

Inserting humor into a “dry” subject can be done, however, and it can make the material more enjoyable to read and more memorable. In William Strunk Jr. and E. B. White’s masterpiece about writing, The Elements of Style, humor sits quietly in the background and serve to illustrate the authors’ points and as a wink to those in the know.

Do not, therefore, say “I feel nauseous,” unless you are sure you have that effect on others.― William Strunk Jr.

The Elements of Style may be a brilliant example of using humor to enliven what some would consider a dry subject, but it’s also an example of how using humor can create controversy. Some people have assailed The Elements of Style as misogynistic because some of its examples that were innocuous when the book was first written (1918) could be offensive in 2023.

“As a mother of five, with another one on the way, my ironing board is always up.”

The issue of authors and publishers needing to be careful (perhaps excessively so) when writing about political and cultural issues is a good argument for avoiding at least certain types of humor. I’d want to be pretty careful with quoting Frank Zappa in a book.

I often use self-deprecating humor, puns, and pop culture references in my technical books. My favorite illustration I’ve used in a book showed that if you count from 0 (as JavaScript does), 10 is the 11th number. The figure shows a volume knob on a guitar amplifier that goes up to 11.

My reference to This is Spinal Tap points to another danger of using even the most mild humor in technical writing — it may come across as forced or dated. Most of my pop culture references are from the early 1980s, and they fly over the heads of many readers who are older or younger than me. When an author attempts a joke that assumes the reader has the same life experience, it’s at best a waste of paper for the reader and off-putting at worst.

If it’s so fraught with danger, why use humor in technical writing? For me, it’s largely to amuse myself. It’s much more fun (for me) to think of writing an instructional or technical book as a challenging creative writing project into which I can inject my own philosophy, point of view, and sense of humor. If I’m having fun with it, I write more.

And, of course, the main reason to use humor is that it may help the material to be more accessible to readers. Many books about programming are simply rewordings of the official documentation. While these types of books often sell quite well, they’re difficult to read. When technical books combine the author’s experience and sense of humor with the hard facts about a programming language or technology, they provide real value to the reader beyond what can be found for free on the web.

What do you think? Have you read any technical or instructional books that use humor effectively? Have you seen instances where attempts at humor in technical writing detract from the material?