Documentation Has a Voice, and Yours Probably Doesn't

Open the docs for almost any B2B SaaS product, and you’ll find prose that reads like the offspring of a DMV waiting room and a thesaurus. While the writing is technically informative, it is dull and lacks a voice.

Except that’s not quite true. It has a voice, one that I like to call “corporate beige,” and that voice conveys something to your reader. It tells them no one in particular cared enough to speak to them.

What voice actually is

Voice in documentation is not jokes or ending every sentence with “and here’s what this taught me about leadership.” It’s not a chatty tone, or pop-culture references, or em-dashes peppered like seasoning—even though I do love em-dashes; curse you, AI.

Voice is the cumulative effect of every small decision a writer makes: which words you choose, how long your sentences run, where you position yourself relative to your reader, what you assume they already know, when you state an opinion, and when you hedge. It’s the answer to a question your reader is subconsciously asking the entire time they’re on your page: who is talking to me right now, and do they know what they’re doing?

If the answer is “no one in particular, and apparently not,” they will leave.

Corporate beige is bad

When teams don’t decide what their documentation should sound like, they don’t end up with neutral prose. They end up with corporate beige, and corporate beige is bad. It looks like this:

It is generally recommended that users may wish to consider configuring the timeout value to an appropriate setting for their use case.

This is text. It is not communication. Strip the hedges out, and you usually find that nobody on the team wanted to commit to a recommendation, so the sentence had to be neutered before it could pass through review. The hedge isn’t politeness. It’s an absence; the negative space left when no one will own a claim.

A reader can feel this insufficiency even if they can’t name it. They come away with a vague sense that the documentation is unhelpful, or that the product is harder than it should be, or that the company isn’t quite sure what it’s doing. The prose has done its work, just not the work you wanted.

A good voice sounds like someone in particular

Stripe’s documentation is a good example of a clear voice that everyone cites because it has been genuinely good for over a decade. You can open a page on webhooks and tell, within a paragraph, that someone made decisions. The sentences are short. The prose assumes you are an intelligent adult who came here to do something specific and would like to leave as soon as that thing is done. There’s no warmth wasted on you, but no condescension either. That’s good documentation that speaks like someone in particular.

The voice in GitHub’s docs does something different. It is warmer, more conversational, and more willing to walk a beginner through a concept slowly. Contrast this with Twilio’s voice, which is more product- and market-focused but still tightly written. None of these companies has documentation that reads the same. All of them read like they were consciously written by someone for someone.

The thing these three examples share is a willingness to commit to a voice and then use it to truly communicate with their customers.

Finding your voice

Voice isn’t a workshop exercise. It’s the result of a few decisions made early on and adhered to through your documentation:

• Who are you writing to? “Developers!” is not a good answer to this question. Instead, think about a specific developer. Are they a senior or junior? Focused or curious? In a hurry or just browsing. Pick one. Your prose will improve immediately.
• What do you sound like when you’re confident? Most teams default to a hedged voice because committees don’t have opinions. Your docs need permission to be assertive and authoritative. Somebody on your team has to be empowered to say, “Don’t do this,” without it being softened to “This is generally not recommended.”
• What do you refuse to do? Voice is shaped as much by what you cut as what you keep. No marketing copy on technical pages. No exclamation points on error messages. No “simply” or “just” to paper over things that aren’t simple. Whatever your lines are, draw them and stick to them.

None of this is style-guide work, per se. A style guide can describe a voice, but it can’t decide on one. That decision has to be made by a person: a writer, an editor, a tech lead with strong opinions and the standing to enforce them. Then, your decisions must be defended every time someone in review wants to soften, hedge, or generalize the prose back into the warm, non-commital oatmeal of “corporate beige.”

Pick a voice

If your documentation reads like everyone else’s, it isn’t because you have no voice. You have one. You’ve accidentally landed on corporate beige: the polite filter, the committee voice, the prose that nobody objected to because it never really said anything.

If you truly want to engage with your customers, pick a voice and stick to it. Almost any deliberate choice will beat the corporate beige you ended up with by accident.