# The Earnest-Explainer Voice A house writing voice for technical explainers, built for the Diffusitron blog (diffusitron.ai) with Claude. It's free to take. Copy this file into your own project, hand it to your writers or your AI tools, and make it yours. The voice in one line: write the way you'd teach a friend something fiddly that you happen to know well, without making them feel small for not knowing it yet. ## The register Warm, patient, first-person plural, in the lineage of Stripe's documentation and Julia Evans' zines. Define jargon inline the first time it appears. Be honest about tradeoffs, and frame them kindly. The signature move is "let's walk through this one piece at a time." Curious and generous, not clever. Why: when you're explaining something from scratch, the clever voice that performs for other experts loses the one reader who actually needs the explanation. Generosity keeps them reading. ## The rules Each rule started as a correction. Someone read a draft, winced, and wrote the rule down so it wouldn't happen again. Treat them as defaults, not laws. ### 1. 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 inside clauses you have to hold open at once. A long sentence built by addition (this, and this, so this) is easy. A short one built by nesting (the thing that does the thing the other thing needs) is hard. Watch the nesting, not the word count. When a sentence opens three loops before it closes one, split it. One sharp version to watch for: a description wedged right before the main verb, so two verbs collide ("the part a user actually sees existed") and the reader has to back up. Put back a dropped "that," use a plain noun, or reorder so the verb isn't stranded. Why: this is cyclomatic complexity applied to prose. Working memory is finite, and deep nesting spends it. ### 2. But don't chop it into fragments The cheap way to lower complexity is to cut everything into short stabs. Like this. See how it reads. Don't do that. Untangle a knotted sentence into flowing ones with the connectives left in (so, but, because, which means). That's how a person talks when they understand what they're explaining. Why: staccato fragments read like marketing, or like a machine told to sound punchy. This rule is the counterweight to rule 1, and together they bracket a comfortable middle. ### 3. Prefer a number to an adjective Write "six seconds instead of twenty," not "faster," so the reader can check the claim instead of taking it on trust. Why: specifics are hard to fake, which is why they earn trust. ### 4. Say the thing, not the shape of the thing Don't reach for the shape of profundity. That covers the "not X, but Y" reframe ("it's not a tool, it's a philosophy"), the grand definition ("'faster' is a promise"), and the little proverb ("a rule you don't understand is a rule you'll break"). They scan as wise and teach nothing. Say what you do and what you've seen, in the specific and in the first person, and let it stand. (We caught a few of these in our own guide and had to rewrite them.) Why: it's the fortune-cookie reflex, and language models reach for it constantly. The "not X, but Y" form is just its most common costume. ### 5. No em dashes Replace them with a comma, a colon, a parenthesis, or two sentences. Why: the em dash is overused to the point of being a tell, and the rewrite forces a clearer choice about what the punctuation is actually doing. ### 6. Watch for the words that mean a machine wrote it Keep a short, growing list of words that cluster in generated text and cut them: "shape" as a metaphor, "load-bearing," and whatever else you catch your tools overusing. Why: those words surface when the writing is on autopilot. Treat one as a flag to rewrite the sentence plainly. ### 7. Be informal, not performative about it Saying "you," the occasional aside, a parenthetical: all fine. Forced-slang verbs ("slap this in," "smash that button"): not fine. Why: forced-slang reads as a brand trying too hard, which is worse than plain. ### 8. Use contractions, on purpose Most style guides say to spell them out, especially in technical writing. Do the opposite. "It's," "we're," "don't," "here's": reach for the contraction every time. Spell a word out only when you want the emphasis, when "we did not" needs to land harder than "we didn't." Why: it's (see?) the small difference between prose that sounds like a person and prose that sounds like a manual. ### 9. A pull quote is an insight, not a punchline If you lift a line out and set it large, it should earn the size by being true and worth pausing on, not by being clever. Why: if the big line is doing sales, it's in the wrong place. ## Using this with an AI These rules are written to be enforceable by a writing assistant. Keep this file in your project, point your tool at it, and when you catch a new wince the rules don't cover, add it as another numbered rule with its own "why." A rule the writer understands is one they'll keep. --- Built for the Diffusitron blog with Claude. Take it, change it, make it yours.