The first time I ever got positive feedback on a document was the first time I indulged myself in a bit of fun.

I was a software engineer on a team tasked with learning a large new system. We were documenting as we went, to help each other and preserve context. But after a lot of writing, and even more reading, it started to feel repetitive.

One day, almost on a whim, I decided to tackle a document in a different way. Instead of listing out the software component's features and limitations as usual, I personified the component and wrote in the style of a dating profile. It started out like this; "Hi, I'm Blue Banner, but you can call me BB…".

I'd never written a document that got so much love! My teammates read it all the way to the end, the thumbs-up reactions rolled in, and people even sent me messages saying they enjoyed reading it. This felt like the holy grail of documentation: something that was not only accurate and useful, but engaging and memorable. And while amusing my teammates was fun, what struck me most was how they remembered it, talked about it, and could find that information when they needed it, weeks and even months later.

While my foray into humour paid off, many technical writers are reluctant to try the same. Humour sits uncomfortably close to things we work hard to avoid: distraction, confusion, and loss of credibility.

Why humour feels risky in technical writing

Technical writing is fundamentally communicating information, and enabling people to complete a task. Anything that might detract from those goals is treated with a healthy dose of scepticism. As a result, a lot of writing advice advocates for simplicity and directness above all else, and including an element of humour naturally raises concerns.

• Distraction: Humour that is unclear, irrelevant, or poorly placed can increase cognitive load. Users might be left puzzling over a pun, or trying to parse your wit to find the facts they need.

• Credibility: Credibility is crucial to being a trusted voice for users and writers may not wish to risk appearing silly or unreliable.

• Tonal mismatch: Humour that doesn't match the audience, brand, or situation can alienate users: Nobody wants slapstick humour when they're trying to recover access to their bank account.

These concerns are absolutely valid. But avoiding humour entirely may mean overlooking the role it can play when used intentionally.

From humour to humanity

Humour is one tool in a writer's toolkit for introducing personality into documentation. Whether we're reading an API specification or a how-to article, a touch of personality reminds us that there is someone on the other side of the documentation.

That sense of connection is important. Documentation is not just information transfer; it is a conversation between someone who has knowledge and someone who needs help. A touch of human personality can reassure readers and build trust by showing that there is someone there who has considered their experience.

Humour is also an engagement tool. We've all experienced the moment when our eyes glaze over halfway through a long set of instructions. A little warmth or personality can encourage users to keep reading, particularly during onboarding, setup guides, or other moments where completing the task requires sustained attention.

The hesitancy is understandable. But done well, humour is additive, not a distraction or a threat to credibility.

Where and when should I use humour? The right tone for the right moment

Understanding why humour helps is important, but knowing how to include it can still be a challenge. Writers can start by finding small opportunities to show personality, acknowledging the person on the other side of the screen. But before adding humour, make sure you have a solid grasp of the situation you're writing for. Ask:

• Who is the audience?

• What emotional state are they likely to be in?

• What is the consequence if they misunderstand?

• Does humour support the user's goal, or compete with it?

Armed with your context, you can decide how much personality and humour the situation calls for. To guide your thinking, it can be helpful to place humour on a spectrum of tone; clinical, warm, light humour, and comedic. Tech writers will likely find that most documentation should live somewhere in the middle of the spectrum, and less at the extremes. 

Clinical

Clinical writing has been considered a default mode for technical writing in the past – it fits the bill of clear, direct, and no nonsense. A clinical tone is blunt and to the point. In medical or legal contexts, clinical writing is expected as the subject matter warrants it. For example, terms and conditions must use appropriate terminology to accurately represent the information they convey.

Warm

Moving up a level, a warm tone isn't necessarily funny, but it is the beginning of personality. It could be as simple as acknowledging the reader, offering reassurance, or writing in a conversational way. For many organisations, this is the sweet spot: professional enough to inspire confidence, while still feeling like it was written by a person.

An organisation might keep the legal wording of its terms and conditions unchanged, but introduce them with a short, reassuring paragraph that explains what the document covers and why it matters. The information is the same, but the experience feels more welcoming.

Light humour

The kinds of phrases that might make us smirk or nod along are good examples of light humour. Documents that use light humour acknowledge a shared experience with their reader by using playful examples, relatable observations or an unexpected turn of phrase. Light humour is often the overlooked opportunity: the middle ground between a purely warm tone and trying to make a document genuinely funny.

This style works particularly well in onboarding flows, success messages, FAQs, and low-stakes support content. Mailchimp's voice and tone guide is a useful example: it encourages writers to use a conversational voice and "subtle" humour, while reminding them that clarity comes before entertainment.

Comedic

Outright comedy is the exception rather than the rule. Some brands have built an identity around being funny, and their audiences expect it. This can be seen in gaming, entertainment, or consumer products like Yarn'N who describe their toilet paper as "soft as a bunny on Easter morning". Most technical writers will rarely need to reach this end of the spectrum; the further you move towards comedy, the greater the risk that the humour overshadows the information.

The spectrum in action

Clinical: Your identity verification is in progress.

Warm: Your identity verification is in progress. We'll be back with you as soon as it's ready.

Light humour: Your identity verification is in progress. This can take a little while, so now's a great time to grab a coffee and scroll guilt free on your phone.

Comedic: Our verification hamsters are sprinting as fast as their tiny legs can carry them.

The examples above show how tone can change a simple onboarding message, but humour can appear in many other places while keeping the user's goal front and centre. Some other opportunities include:

• Personas and examples: Instead of generic copy, create realistic scenarios or characters that help users understand how a feature works. This was the approach I took with Blue Banner.

• FAQs: A small moment of personality can make a frequently asked question feel more conversational, particularly for common questions users may feel hesitant to ask.

• Success moments: Confirmation messages, empty states, or completion screens are opportunities to celebrate progress and make an interaction feel rewarding.

Choosing the right level of humour is ultimately the same judgement call we make throughout technical writing. We already consider our audience, their goals, and the context they are operating in when deciding what information to include and how to present it. Tone is no different. Thinking of humour as a spectrum makes it less of an all-or-nothing decision and empowers us to find the right balance.

Knowing when not to use humour

Good use of humour requires judgement. The same care for our readers’ experience that encourages us to add personality also tells us when to leave it out.

Using humour effectively starts with understanding your audience. A joke, phrase, or playful reference that delights one group of users may confuse or alienate another. Humour that relies on cultural references, wordplay, or assumptions about shared experiences should be approached carefully, particularly for global audiences. There are also situations where users need reassurance and clarity more than personality. During an outage, security incident, billing dispute, or other high-stress moment, humour can feel dismissive even when it is well intentioned.

You don’t need to make people laugh

Since writing about BB, the Blue Banner, I feel more confident writing with my own voice, including the quirks and humour that make my writing feel mine.

Readers aren't likely to finish a help article thinking, "What a hilarious document, I’ll just wipe the tears from my eyes”. But they might finish it feeling that someone understood what they were trying to do, and made the process a little easier. Humour doesn't need to be at odds with informing and guiding, it can help writers achieve these goals.

We don't need to write documentation that makes people laugh. Instead let's write documentation that reminds people there's a human trying to help.