A few days ago I published a repository for the English Programming Language, a tongue-in-cheek parody of README files. I had a hunch and posted it on Hacker News at 3 AM. When I woke up, the repo was on the front page and already racked up 200 stars on GitHub. Not bad for a nerd joke.
But then again, why would someone write humorous technical documentation?
The idea of creating the english-lang repository was born out of a tweet I published earlier the same day as a reaction to a comment in Hacker News that shunned the whole idea of docs-as-code because… docs don’t compile. In the tweet I had pushed the implications of docs as code to the limits, but I wanted to go further. A month before I had thoroughly enjoyed reading the README of DreamBerd, a parody repo that mocked novelty programming languages and their upbeat tone. I wanted to do something similar and the time proved right. As a fan of esoteric programming languages, I couldn’t help it and wrote the README in an hour.
Some of the ingredients I added to the repository to make it a more credible parody included code snippets, GitHub shields (or buttons), a serious and authoritative tone similar to Wikipedia’s presentations of programming languages, as well as sections illustrating the core aspects of the language. It had to read like a real README file. The extreme popularity that large language models and machine learning are currently enjoying helped propel the visibility of the repository; for example, several readers commented on the implications of using a natural language to “program” large language models. The joke sparked semi-serious conversations on Hacker News, which means that the README indeed stroke the right chords.
The first reason for writing humorous documentation is that even technical writers sometimes need to let some steam off and goof around during stressful situations. As Geoff Hart wrote in the summary of Humour in technical communication (2001):
Even where the situation requires a measure of seriousness, humor may still be appropriate. As John Cleese, famed member of Monty Python, has observed, “serious doesn’t inevitably mean solemn”. Humor can release stress, make both the audience and the author feel better, and generate beneficial health effects (hence the phrase “laughter is the best medicine”). Moreover, […] we spend far too much time at work not to enjoy ourselves.
The second reason is that, while documentation is no joke, jokes can help you become a better writer. Humor is taboo in tech comm, but it can sometimes help make dense technical documentation more digestible and close the gap between the docs and its readers. David Roberts, the author of a dissertation from 2013 titled The Ethos of Humor in Technical Communication, concludes the following:
While the use of humor as a rhetorical strategy has long been suspect or completely denied as beneficial to serious technical writing, current technical communication proves that this style of writing can make a positive contribution rhetorically. The choice to use humor rather than keep it separate from the conversation has been made, to some degree or another, in nearly every field, and has been used in serious documentation. So too has humor made its way into technical documentation and arguably continues to grow as the technical writing field continues to expand.
Humorous documentation like the README file I wrote doesn’t support any real product, of course, but it does help train the kind of skills required to insert humor in technical documentation where appropriate. It also has the additional benefit of helping writers find their own voice in a field that tends to avoid the matter entirely. (I discussed the topic of personality in documentation a while ago.)
I also blame one my favorite Italian writers, Umberto Eco, for writing some hilarious fake tutorials in How to Travel with a Salmon. Almost all of Eco’s writings are proof that highly intellectual topics can be presented under a humorous form without detracting from their complexity or importance. (Remember the conversation on laughter from The Name of the Rose? Let’s just say I don’t side with Fray Jorge da Burgos.)
As a rule of thumb, yes, you should avoid humor in contexts where humor can be a hindrance. Jokes are not only hard to translate and localize, but can be perceived as a waste of time. Knowing when to insert humor is difficult and only comes from knowing your audience extremely well. As this reply in Stack Exchange puts it,
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. […] Humor in learning materials is another matter.
And yet sometimes there is room for humor even in the worst of situations. When stressed my goofiness increases and I resemble Hoban “Wash” Washburne from Firefly, with his sarcastic one liners and remarks. Do I let that humor enter the troubleshooting docs I write? Never. But I’d do it when writing learning materials.
Let me end this post with the conclusion of Humor and technical communication: the culture, the texts, the implications (1996), a dissertation by Kathleen Ann Hurley:
Technical communicators operate in a river of words. What has been overlooked is at least one tributary or underground stream which contributes to the river, the world of humor, which brings with it a laughable perspective, and one in which writers and readers actively participate on a regular basis.
Acknowledging this tribute will be a first step; it will be a recognition that technical communicators operate in an extremely complex body of water. Using what we know about the river will be the second step: and while the challenge of dealing with complexity is enormous, the results may provide both writers and readers a significant means of understanding each other in a more complete manner.