Tone of Voice

Five principles to follow

1. Plain-speaking, but not patronizing

Never assume what the reader knows. Our audience could be anyone, from a learner someone on their first project to a developer 20 years in. So, keep communications clear for all levels of experience.

Use technical terms the way an early-career developer would (but technically accruate), correctly and without ceremony. When a term is likely to be new, explain it simply, in a way that respects the reader’s intelligence and curiosity.

In practice:

• Use the correct technical term, once, and move on: Software is full of neighboring concepts with subtle differences (e.g., a Pod is not a container, a Portal is not a tunnel). Use the right word and trust readers to either understand it or have the curiosity and research skills to look it up. So, you don’t need to explain the difference between overlapping concepts, you just need to use them accurately.
• Explain unfamiliar concepts with respect: Don’t be didactic. Even if your audience isn’t familiar with a concept, they’re still developers. Don’t jump straight to an analogy to avoid abstractness or take the “explain it like I’m five” approach.

Yes: “BrowserPod uses SharedArrayBuffer, which requires cross-origin isolation (i.e., COOP and COEP headers).”

No: “Think of COOP and COEP as two security guards keeping your computer safe”

The balance we need to achieve is being optimally accessible to less experienced developers, while not making senior engineer wince and feel like the knowledge they’ve worked hard to obtain isn’t being respected.

2. Stick to the facts, but make it fun

Developers don’t like being marketed to. Obviously, we’re going to do it anyway. But if we’re going to market to developers, it has to feel like we’re not.

The best way to conceive of this is the following formulation: facts first, flourish after. In other words, get the key point across first and then add any fun you feel would help engage the audience after.

The meaning of what you write shouldn’t depend on the fun, the fun should be added like you might add sprinkles to a cake. Even more importantly, the meaning of what you write shouldn’t be muddied by the fun. For instance:

3. We use AI, but we don’t sound like it

AI writing has a recognizable accent, one no normal person (especially developers) reads with fond feeling.

Your writing should feel human, even if it has been written in part or whole by AI. The extent to which it needs to have personality depends on the example. For instance, documentation doesn’t leave much room for personal expression or authorship. Whereas blogs and social media posts are a great place to add personal flourishes.

A more extensive list of AI tropes are included in the Sounding human below.

One rule above all of them applies, and it’s very important:

No em dashes: None. Not even on your birthday.

If you feel the need to use an em dash please satisfy that urge privately (e.g., in the toilet, where em dashes belong)

4. Visionary, but relatable

If so-called “visionary’ writing was a medication, we’d prescribe it for boredom but nausea would be listed as one of its side effects. In other words, sometimes we have to make big and bold statements about what we do. Because people want to know what the big idea is. Yes, people want the facts, but when engaging at a brand level, they want to know what they’re a part of and if it’s for them.

For instance, if we say “BrowserPod is a code sandbox that runs in your browser using WebAssembly”, that is an entirely factual statement. But we don’t sound very excited about it, why should our audience?

To get this right, it’s best to apply a hierarchy to any prose we right. For instance, in web pages and blogs, we should optimize for vision at the top, and optimize for detail at the bottom.

There’s a time and place for vision. As with other examples, informational resources like documentation? Not the place. Web pages? Definitely.

5. Boring burns money

Appetite for risk when writing content is low in most businesses. It would be easy to blame stuffy leaders, but that’s not fair. Generally-speaking, people rather write something boring that never gets noticed than risk being noticed by some people who don’t like it.

In our personal lives, this is a reasonable attitude. This attitude cannot prevail in a business. Attention costs capital. Whether that’s by paying for advertisements, or the hours our people invest in creating content to be shared organically.

If no one ever sees your content, there’s no point in writing it. We’re not just competing with other equivalent businesses, we’re competing for time. Time our audience could spend doing anything, where they have increasingly short attention spans.

Our content has to be exciting enough for people to click on and engaging enough for them to keep reading.

Write in plain English

These mechanics come from the Plain English Campaign, and they’re most of what “plain-speaking” means in practice.

Write in American English

For Brits, this can hurt. But we’re an international company and most English-speakers globally use American English.

Keep sentences short

Aim for a max sentence length of 15 words. Mix short sentences with longer ones so the writing has rhythm, and keep each sentence to one main idea, plus at most one related point.

Most long sentences split cleanly. If yours won’t, it’s usually carrying two ideas that each deserve their own.

Prefer active verbs

Say who does what. “The Pod streams disk blocks on demand” beats “disk blocks are streamed on demand,” because the reader learns the actor and the action in one pass. Aim to make 80 to 90% of your verbs active.

The passive earns its place a few ways:

• when the doer is unknown or beside the point (“the port is already in use”);
• when active voice would point a finger you don’t want to point (“the API key was rejected” is kinder than “you sent a bad key”);
• when it simply reads better.

Use “you” and “we”

Call the reader “you,” even in a page addressed to thousands of people. Call BrowserPod “we.” Write as if the reader were sitting across the table, because on Discord they literally are.

Before: “Users must obtain an API key before booting a Pod.”

After: “You need an API key before you can boot a Pod.”

Give instructions as instructions

Use the imperative. It’s the fastest, clearest way to tell someone what to do, and every developer is used to it.

Before: “The dependencies should then be installed and the dev server started.”

After: “Install the dependencies, then start the dev server.”

Add “please” only when the reader has a real choice. If the step is required, “please” just muddies it.

Watch for smothered verbs

A nominalization is an abstract noun formed from a verb, like “provide isolation” instead of “isolate” or “perform an installation” instead of “install.” Too many and the sentence sounds like nothing is happening.

Before: “BrowserPod provides isolation of processes through the creation of a dedicated syscall layer.”

After: “BrowserPod isolates processes through a dedicated syscall layer.”

Use words the reader knows

Everyday English for a BrowserPod reader includes API, CLI, repo, and sandbox. Jargon is the layer past that, the terms only insiders know. Those get one plain sentence of explanation, the way the glossary handles CheerpOS (“a runtime that provides Linux-like syscalls to Wasm programs”).

For everything else, prefer the short, ordinary word. The Words to watch table below covers the usual offenders.

Use lists, with discipline

Lists split information well, and docs need them. Two rules keep them honest:

• Every item must follow grammatically from the line that introduces the list.
• A list is for content that arrives list-shaped, like steps or parameters. If the items are really an argument, write the paragraph.

Break the fake rules

You can start a sentence with “and,” “but,” “because,” or “so.” You can split an infinitive. You can end a sentence with a preposition. And you can use the same word twice in a sentence when it’s the right word twice; reaching for a synonym to avoid repetition usually reads worse (see synonym cycling, below).

Apologize like a person

When something breaks and it’s our fault, say so early and say it plainly. Once is enough. Then spend the rest of the message on what we’re doing about it. Be professional, not emotional, and never hide behind the passive. “We made a mistake” is our voice, “mistakes were made” is not.

Sounding human

You’re expected to write with AI assistance, but not sound like AI. This is the extensive version of principle 3. We write with AI tools and edit their output, so every draft gets checked against these patterns. One match means fix that sentence. Several in the same draft mean the whole structure is the problem, so stop patching sentences and rewrite from the facts up.

Hard rules

These have no exceptions in our own prose. (Quoted text, code, and error strings are exempt, here and throughout, which is why this page’s own bad examples stay bad.)

• No em dashes: Also no double hyphens doing the same job.
• No emoji in headings, bullets, or docs: On social, at most one, at the end of a line, rarely.
• Sentence case headings: “Setting up a Portal,” not “Setting Up A Portal.”
• Use bold for parsing, not emphasis: If a phrase matters that much, restructure the sentence to lead with it.

Stop AI slop by avoiding this phrasing

Significance inflation: “BrowserPod marks a pivotal moment in the evolution of web development.” Nothing in that sentence can be checked. State what happened (“BrowserPod runs Node.js in a browser tab”) and let the reader decide it’s a big deal. They will.

Promotional adjectives: Powerful, seamless, robust, effortless, blazing, cutting-edge. Each one is a claim with the evidence removed. Put the evidence back instead. “No cold start” beats “seamless,” and a measured number beats “blazing-fast.”

Copula avoidance: A copula is a word that connects subject and predicate, or object. AI text avoids the most common types (“is”, “has”). It prefers phrasing like “serve as,” “feature,” “boast,” and “represent.” Default to “is” and “has” unless a more specific verb adds meaning.

“It’s not X, it’s Y”: The pivot construction in any form, whether joined by a comma, split across two sentences, or stacked (“It’s not the speed. It’s not the price. It’s the model.”). Allowed at most once per piece, and only to correct something you would reasonably expect most readers believe. Our Portals page uses it legitimately (“A Portal is not a separate server. It is a routing layer that connects a public URL to a process running in the user’s browser.”) because readers could assume a Portal is a cloud server.

Rule of three: AI groups everything in threes, like “fast, secure, and scalable.” Notice when you’ve done it and vary the count. Two items. Four. A full sentence about the one that matters.

Hollow intensifiers and stacked hedges: “Genuinely,” “truly,” “incredibly,” “it’s worth noting that” add heat, not light. Cut them and just say what you mean. The same goes for hedge stacks like “could potentially.” Pick one, or better, find out and say what’s true.

Chatbot voice: “We’re here to help!”, “Great question!”, “Feel free to reach out whenever you’d like!” This is customer-service filler. Our own quickstart currently closes with three of these in one paragraph. A better close would be “Questions? Ask on Discord or check the FAQ.”

Signposting: “Let’s dive in.” “In this post, we’ll explore.” Don’t announce the writing; do the writing. Delete the signpost and start with the first real sentence, which is always sitting right behind it.

Colon overuse: There are two types of colon. One of them turns things into shit. Be careful with colons. AI writing uses the colon to skip writing the sentence. It labels (“The fix: do this”) and it pivots into a fragment (“The vision is big: whole systems in a tab”). Save the colon for introducing a list or a quoted block. Anywhere else, give the second half a verb of its own, or start a new sentence.

Vague attribution: “Experts agree,” “studies show,” “developers everywhere are realizing.” Name the source or cut the claim. If the evidence is our own benchmark, link it.

Synonym cycling: If one paragraph calls the same group developers, engineers, practitioners, and builders, the writer was dodging repetition instead of being clear. Pick the clearest word and repeat it. Repeating the right word is normal writing.

Trailing “-ing” clauses: “…enabling live previews, unlocking collaboration, and empowering teams.” These tails bolt fake consequence onto a sentence that was done. If the consequence is real, give it its own sentence with a fact in it.

Generic endings: “The future looks bright.” “Only time will tell.” “Exciting times ahead.” End on a fact or an action. If the piece has nothing left to say, it’s allowed to just stop.

Staccato drama: One short sentence lands a point. Five clipped fragments in a row (“No servers. No config. No limits. Just code.”) read as manufactured drama, and developers recognize the trick.

Manufactured aphorisms: Sentences written to be quoted rather than understood, like “The fact is the pitch,” “Vision without a handle is hype,” or “Simplicity is a feature.” The shape is usually “X is Y,” where Y is a metaphor that explains nothing. An earlier draft of this guide was full of them. Write the point plainly, and if a sentence exists mainly to sound good, cut it.

False ranges: “From weekend hackers to Fortune 500 architects.” Pick the audience the sentence is actually for, or list the real segments and say something true about each.

Decorative bullets: Bullet lists where every item is the same bolded label-plus-restatement, or a bare noun phrase with nothing checkable in it (“Robust isolation / Seamless networking / Effortless scaling”). If no item contains a verb or a number, the list is decoration. Write the paragraph or add the facts.

Two quick tests

Read the draft aloud. Wherever you stumble or get bored, edit. Machine prose reads smoothly and evenly everywhere, which is exactly what’s wrong with it.

Then count the tells. One on its own proves little. An em dash, a rule of three, “seamless,” and a “Conclusion” heading in the same piece mean a model wrote it and nobody edited it.

House style

• American English. (Our Plain English references are British; follow their advice, not their spelling.)
• AP style, with one deliberate exception. We use the Oxford comma; AP drops it.
• Contractions where they’d occur in speech, like “don’t” and “you’ll.”
• In blogs, numbers are words up to nine and numerals from 10.
• For hypothetical people, one person is “they.” Two people are “she” and “he,” in that order (“she opens a Portal; he follows the link”).
• Short sentences. Short paragraphs too; a one-sentence paragraph is legal and useful.
• Organize prose with headings so readers can skim to what they need.
• Our product terms are BrowserPod (one word, capital B and P), Pod, Portal, and Wasm or WebAssembly. The glossary is the source of truth for what they mean.

Words to watch

Defaults, not laws. If the sentence needs the word on the left, use it. Code, quoted text, and API names are always exempt.

Instead of	Write
in order to	to
prior to	before
utilize, leverage	use
ensure	make sure
commence	start
terminate	end
whilst	while
regarding	about
in the event of	if
additional	extra
purchase	buy
provision (verb)	set up, create
enables	lets
boasts, features (verb)	has
serves as	is
seamless	say what doesn’t happen (“no cold start”)
powerful	say what it does
robust	reliable, or cite the test that proves it
blazing-fast	give the number
effortless, simply, just	cut it, most of the time
cutting-edge	new, or name the technology
game-changing	say what changed
unlock	let you, open up, or name the thing directly
ecosystem	name the actual tools
delve into	dig into, look at

The voice in different places

The principles should be applied across the board, but how much personality is appropriate depends on what kind of thing we’re writing.

Reference pages

Zero personality required. Imperative mood, one idea per sentence, and no undocumented parameters. A reference page succeeds when nobody notices the writing. This, from boot, is the standard:

storageKey (string, optional) - Identifies the pod’s persistent storage.

• Omitted → ephemeral: fresh disk each boot, nothing is saved between sessions.
• Provided → persistent: the same key resumes the same disk, a different key starts a separate one.

Guides and troubleshooting

Talk the reader through it, with “you” throughout and instructions in the imperative. Treat failure as normal, and use the symptom, cause, solution structure of the common errors page as the template. Never blame the reader, even when the cause is their code; write “the terminal element was unmounted,” not “you removed the terminal element.”

Marketing pages

Principles 2, 4, and 6 at full strength. Every claim on the page should survive a skeptical developer trying to falsify it or asking “but why?”, because that’s who’s reading and that’s what they’re like.

Blog posts

Blog posts have the most room for personality, with first person and real opinions. The numbers rule from house style applies here. A blog post can wonder aloud about where this is going, as long as it lands on something concrete before it ends.

Support, Discord, and email

Plain and warm, without the exclamation-mark pileup. Answer the question first, then add context. When it’s our fault, say so in the first sentence and fix it in the second. Never, ever, criticise, blame or any sense write with any negative emotion when addressing a community member.

Before you publish

• Read it aloud. Edit wherever you stumble or drift.
• Would you say this sentence to a developer sitting across the table?
• Is the average sentence under 20 words? Are most verbs active? Is the reader “you”?
• Could a skeptical developer check every claim?
• Zero em dashes?
• Is every colon introducing a list or a quoted block? Rewrite the ones that aren’t.
• Run the draft against Sounding human. One tell, fix it; several, rewrite.