Where this came from
The voice has a name we use between ourselves: the earnest explainer. It's warm, patient, and first-person plural, in the lineage of Stripe's documentation and Julia Evans' zines. It's the voice you'd use to teach a friend something fiddly that you happen to know well, without making them feel small for not knowing it yet. We write the engineering posts this way because the alternative, the clever voice that performs for other experts, loses the one reader we actually care about: the person who came here to learn the thing.
Most of what follows started as a correction. We'd read a draft, notice something that made us wince, and instead of fixing it just that once, we wrote the rule down so it could be applied everywhere, by anyone, including the tools that help us write. Most of the voice is really just a pile of remembered winces. Here's the pile.
Keep sentences shallow, not short
Treat a sentence like a function. What makes one hard to read is rarely its length. It's the nesting, the clauses tucked inside clauses that you have to hold open all at once. A long sentence built by addition (this, and this, so this) is easy to follow. A short one built by nesting (the thing that does the thing the other thing needs) isn't. So we watch the nesting, not the word count, and when a sentence opens three loops before it closes one, we split it. This is the rule that started this whole page. We think of it as cyclomatic complexity for prose: in code and in writing alike, it's the branches inside branches that cost the reader, because working memory is finite.
There's a sharper version worth naming. When a description gets wedged right before the main verb, two verbs end up side by side and you have to back up to re-read. We had one in another post: "before the part a user actually sees existed," where "sees" and "existed" collide. The fixes are small: put back a dropped "that," swap the description for a plain noun, or reorder so the verb isn't left stranded at the end.
But don't chop it into fragments
The cheap way to lower complexity is to cut everything into short, flat stabs. Like this. See how that reads. We don't do that. The fix for a tangled sentence is to untangle it into flowing ones, with the connectives left in (so, but, because, which means), because that's how a person actually talks when they understand what they're explaining. The staccato voice has its place, in a manifesto, on a landing page. It's not how you teach.
Prefer a number to an adjective
When something gets quicker, we try to say how much. We'd write "six seconds instead of twenty" rather than "faster," because you can go and check the number yourself. Made-up specifics are easy to catch, which is part of why we lean on them.
Say the thing, not the shape of the thing
Some sentences reach for the shape of profundity instead of just making the point. The "not X, but Y" reframe ("it's not a tool, it's a philosophy"). The grand definition ("'faster' is a promise"). The little proverb ("a rule you don't understand is a rule you'll break"). They scan as wise and teach nothing, and language models reach for them constantly.
We know the pull firsthand, because we caught ourselves. An earlier draft of this very page opened the section just above with "'Faster' is a promise. 'Six seconds instead of twenty' is a fact the reader can check," and the intro ended on "a rule you don't understand is a rule you'll break the first time it's inconvenient." Reading our own guide back, we winced. So we rewrote them to say what we actually do: write the number so you can check it, and give each rule a reason, because when we forget the reason we stop following the rule.
No em dashes
This one is a house rule more than a law of nature, and we keep it strictly. The em dash is overused to the point of being a tell, and banning it forces a small useful decision every time: is this a comma, a colon, a parenthesis, or really two sentences? Nine times out of ten the rewrite is clearer than the dash would've been.
Watch for the words that mean a machine wrote it
We keep a short, growing list of words that cluster in generated text, the ones that surface when the writing is running on autopilot. Shape as a vague metaphor. Load-bearing as a knowing wink. When one appears, we treat it as a flag that the sentence stopped being thought and started being filler, and we write it again plainly.
Be informal, not performative about it
Saying "you," the occasional aside, a parenthetical: all fine, all human. What we avoid is costume casualness, the forced-slang verbs ("slap this in," "smash that button") a brand puts on to seem relaxed. It reads as exactly that, a brand trying, which is worse than just being plain.
Use contractions, on purpose
Most style guides tell you to spell them out, especially in technical writing. We do the opposite. "It's," "we're," "don't," "here's": we reach for the contraction every time, because it's (see?) the small difference between prose that sounds like a person and prose that sounds like a manual. We spell a word out only when we want the emphasis, when "we did not" needs to land harder than "we didn't."
A pull quote is an insight, not a punchline
When we lift a line out and set it large, it has to earn the size by being true and worth pausing on, not by being clever. "A fixed pool turns farming into an act of self-dilution" is the kind of sentence we will enlarge. A zinger isn't. We'd rather hand you a sentence to sit with than one that's trying to sell you something.