Blog writing style guide

Notes for engineering blog writing. The goal: read like a human engineer wrote it, not like it came out of a chatbot. Two big reasons. It's more credible with a technical audience, and obvious AI-generated prose reads as low-effort regardless of how good the underlying work is.

0. The goal is a human voice, not a word filter

Read this first. Everything below is a heuristic toward prose a person would write, not a checklist to satisfy mechanically.

Over-correction is its own tell. Prose that dodges every banned word but comes out clipped, choppy, and stripped of personality lands in a different uncanny valley. Keep the occasional analogy, aside, and bit of structure that a real writer would use.
Don't swap one crutch for another. If every em-dash becomes a parenthesis, parentheses are the new tell. If banned words get replaced by near-synonyms, nothing changed.
On the dash rule specifically: a single deliberate em-dash from a human reads fine. The tell is the reflexive, high-frequency habit. The rule here stays at zero because a generator can't reliably tell its reflexive dash from a deliberate one, so the safe default is none. Apply that spirit everywhere. Natural writing is the target; the bans are the fastest route there, not the point.

1. Punctuation

No em-dashes or en-dashes (—, –). This is the single loudest AI tell. Replace with:
- a comma, when the aside is mild: ~~"the server fetches it — then parses"~~ → "the server fetches it, then parses";
- parentheses, when it's a true aside: "the metadata endpoint (only reachable from inside the instance)";
- a colon, when the second half explains the first: "one design fact: the server fetches a URL a stranger chose";
- a period. Two shorter sentences usually beat one dash-spliced sentence.
Don't replace an em-dash with " - " (spaced hyphen). That's just a different tell. Restructure instead.
Use hyphens only for compound modifiers ("threat-model-first", "self-contained").
Straight quotes and apostrophes are fine; don't fuss over curly vs straight.
Avoid the ellipsis "…" for trailing-off drama.

2. Words and phrases to avoid

These are overused by Claude/LLMs and read as AI filler. Cut them or say the plain thing.

Nouns / metaphors:

load-bearing (as in "the load-bearing assumption")
landscape ("the research landscape", "navigate the landscape") — use sparingly; "the research on X" is fine
realm, world ("in the realm of", "the world of")
tapestry, symphony, orchestra
testament ("a testament to")
cornerstone, bedrock, linchpin
treasure trove, wealth of, myriad, plethora
game-changer, game-changing
deep dive, "let's dive in"
compass needle / north star (as metaphor)

Verbs:

delve, delve into
leverage (use "use")
underscore, highlight (as in "this underscores") — use "shows"
unlock, unleash, supercharge, turbocharge
elevate, empower
boast ("the tool boasts X")
foster, cultivate
navigate (metaphorical)
earn their keep, pull their weight

Adjectives:

robust, seamless, seamlessly
crucial, pivotal, vital, paramount
cutting-edge, state-of-the-art (unless literally citing SOTA research)
meticulous, meticulously
comprehensive, holistic
rich (as in "rich, actionable insights")
powerful (as filler)
elegant, elegantly

Tech-blog filler:

"at scale"
"under the hood" (overused)
"battle-tested"
"first-class citizen"
"out of the box"
"sane defaults"
"the beauty of X is"
"essentially", "basically" (as filler)

Minimizing words:

"just", "simply", "of course", "obviously". "Just run this command" and "simply configure the webhook" alienate the reader who is stuck precisely because it wasn't simple. Cut the minimizer and describe the actual steps.

Connectives / filler openers:

"It's worth noting that", "It's important to note", "Notably,"
"Furthermore," / "Moreover," (once in a while is fine; not every paragraph)
"In today's fast-paced world", "In an era of"
"At the end of the day"
"Here's the thing:", "Here's the kicker:"
"That said," (overused)
"Rest assured"
"Honest ___" as a label ("Honest limits", "Honest caveat", "To be honest"). Just state the caveat.

3. Contrastive reversal and rhetorical cadence (the loudest tell)

This is the pattern peer reviewers flag first, so treat it as the top priority. State the point directly on the first pass. Do not set up a weak or obvious framing just to reveal the "real" point in the next sentence.

Ban the "not X, but Y" family in all its forms: "not X, but Y," "it's not X, it's Y," "the issue isn't X, it's Y," "it wasn't X, it was Y," "not just X, but Y," "X, not Y." Also the softer pivots: "rather than," "instead of X, do Y" used for contrast. Say what it is.
- Bad: "Treat the numbers as directional signal, not proof."
- Good: "This is a sample size of one, so the counts are a rough signal and the exact numbers are noisy."
No mirrored sentence pairs for emphasis. Don't restate the same idea with slightly different wording for drama. Avoid thesis-antithesis cadence, binary contrast framing, fake-outs, over-signposted pivots, and presentation-style escalation.
- Bad: ""Validate inputs" is noise; naming the real threat is signal."
- Good: "Name the asset an attacker wants and the data flow that reaches it."
Write flat, direct, decisive. Say the point once. Add nuance only when it changes the meaning. Prefer plain diagnosis over rhetorical structure. A direct negation used to state a fact ("it does not catch subtle flaws") is fine; the banned thing is the setup-then-reveal rhythm.

4. Sentence, structure, and formatting patterns to avoid

These are structural tells: the phrasing rhythm and layout, not individual words.

Negative parallelism / "not just X, but Y". "It's not just a benchmark, it's a philosophy." "This isn't about tools; it's about mindset." Kill on sight. State what it is.
The dramatic one-liner reveal. "Read that again." "And that changes everything." "The difference is the whole lesson." One per article, maybe. Not a paragraph-ending habit.
The colon-drama reveal. "The punchline up front:", "The result:", "The kicker:". Occasional is fine; it becomes a tic fast.
Rule of three everywhere. "faster, cleaner, safer." "the what, the why, and the how." Real writing varies list length; three-beat lists in every paragraph are a tell.
Rhetorical-question section openers. "So what does this actually mean?" "But how does it work under the hood?" "You might be wondering why we didn't just cache it." State the point, or ask a real question and immediately answer it with something the reader couldn't guess.
Telling readers what they think or feel. "You've probably hit this." "We've all been there." "If you're like me, you…" Assume a smart reader and get to the content.
Whether-you-clause openers. "Whether you're a solo dev or an enterprise team, …" Cut it.
Over-signposting. "Here's the most useful part." "Now for the interesting bit." "The key takeaway is." Just say the thing; let it be interesting on its own.
Tour-guide transitions. "Now let's look at…" "Having covered X, let's turn to Y." "As we can see above." Headers and paragraph breaks already do this.
Formulaic section labels. "X, in one paragraph." "The TL;DR." "In a nutshell." Name the section for what it contains ("The results", "How we tested").
Hedge-and-pivot. "While X is true, it's also true that Y." Say Y.
Summary sentence that restates the paragraph. LLMs end paragraphs by re-summarizing what they just said. Delete the last sentence if it only repeats.
"In other words" / "Put simply" restatements. Same instinct: say the thing, then say it again slightly differently. If the first version was clear, cut the second.
Empty superlatives. "dramatically", "vastly", "incredibly", "remarkably". If the number is dramatic, the number carries it.
Bold-for-drama. Bolding whole sentences for emphasis. Reserve bold for genuine scannable keywords, not applause lines.
Bulleting everything. LLMs turn every pair of related sentences into bullets. Prose is the default; bullets are for genuinely parallel, scannable items. (A style guide is one of the few documents where dense bulleting is correct, so this file is the exception, not the model for article prose.)
Emoji in headers or as list markers (✅ ❌ 🚀 🔥). Reads as content marketing.
Tables doing a sentence's job. Tables earn their place for real multi-dimensional comparison, not a two-row "Feature / Benefit".

5. Article shape: intros, conclusions, titles

Document-level structure: the openings, closings, and headlines that give away a generated draft.

No throat-clearing intro. Cut "In this post, we'll explore / cover / dive into…" and the bulleted "what you'll learn" preview. Open on the problem, a concrete failure, or the surprising result.
No recap conclusion. "In conclusion, we've explored…" that lists what the article already said. End on the consequence, the thing you'd do next, or just stop.
Kill the "Enter X" product reveal. "Enter Kubernetes." "That's where Redis comes in." Introduce the tool by what it does.
Titles. Avoid the content-mill shapes: "The Ultimate Guide to X", "Mastering X", "X: A Comprehensive Guide", "Why X Is the Future of Y", "N Ways to…". State the specific claim or result ("We cut p99 latency 40% by deleting a cache").

6. Code and commands

Specific to technical writing. The code is often where a generated post gives itself away, even when the prose is clean.

Don't narrate the code after the block. LLMs paste a snippet and then walk it line by line: "First we import the client, then we define the handler, then we loop over the results." If the code is readable, the walkthrough is filler. Explain the non-obvious decision, the gotcha, or the reason it's written that way.
Comment only where a reader would actually wonder. Delete comments that restate the line (# increment the counter above i += 1).
Use realistic values. foo/bar/baz, example.com everywhere, and your_api_key_here read as synthetic. Plausible names (checkout_service, user_id, a real-looking path) read as code that ran.
Don't present untested code as tested. If you didn't run it, label it a sketch. A technical reader will run it and find out.
Keep snippets minimal. Show the lines that matter and elide the boilerplate with # .... A 40-line block where 5 lines carry the point buries the point.

7. The voice we want

Direct and concrete. Prefer the specific noun and the real number over the abstraction.
Vary sentence length. Some short. Some longer with a clause that earns it.
Plain verbs: use, show, find, break, miss, fix, run, measure.
Confident but honest about limits (the research already models this well, so keep it).
Have a take. Engineers read blogs for a point of view, not a neutral survey. "I think reaching for an ORM here is usually a mistake, and here's the case that changed my mind" beats "there are pros and cons to ORMs." Relentless neutrality reads as evasion.
Calibrate confidence to what you actually did. Separate what you measured from what you're guessing. "Benchmarked on one box, so treat the absolute numbers as rough" is more credible than a bare claim or blanket hedging.
Never invent a specific to sound concrete. A made-up benchmark, a plausible-but-wrong version number, an invented quote: caught once, and a technical reader discounts the whole piece. If you don't have the figure, give the shape ("a few hundred milliseconds, didn't measure precisely") or link the source. Real specifics come from real artifacts, so link the RFC, the issue, the commit, the changelog.
It's fine to start a sentence with "But" or "And" occasionally. It's fine to use contractions.
When in doubt, read it aloud. If you wouldn't say it to a colleague at a whiteboard, rewrite it.

8. Quick pre-publish checklist

Search the document for — and –. There should be zero.
Ctrl-F the §2 words you know you lean on (leverage, robust, crucial, underscore, landscape), plus "just" and "simply".
Scan paragraph endings for restated-summary sentences and dramatic one-liners. Delete any that only repeat.
Count three-beat lists. More than one per section, vary them.
Read the intro aloud. Does it sound like a person or a press release? Cut any "In this post we'll…" opener and any recap conclusion.
Check each section opener. If it's a rhetorical question, rewrite it as a statement.
For each code block: is there a line-by-line narration after it? Delete it and keep only the non-obvious why.
Confirm every number, version, and quote is real. If you didn't measure or verify it, say so or link the source.
Scan formatting: bulleted lists that should be prose, emoji in headers, tables doing a sentence's job.

kristovatlas/STYLE-GUIDE.md

Select an option

No results found