Technical Writing Style Guide
Write docstrings, READMEs, commit messages, and PR descriptions that read like human technical documentation instead of LLM output — six concrete 'tells' with before/after rewrites, a smoothness diagnostic for prose that sounds authoritative while stating one fact three times, and industry-metaphor substitution tables ('surfaces' to 'raises/returns/logs', 'wired through' to 'passed as a parameter').
The single biggest giveaway that documentation was LLM-written isn't a specific word — it's writing that states significance instead of mechanism, like 'this ensures the sandbox remains secure' instead of the actual fact: every operation runs relative to a Dir opened at mount time, so .. and symlinks can't escape it.
Who it's for: engineers writing docstrings, READMEs, and PR descriptions who want them to read like real documentation, tech leads establishing a house writing style for AI-assisted contributions, anyone reviewing generated documentation that feels subtly off but can't name why, teams tired of code comments padded with adjectives instead of the actual mechanism or cost
Example
"This docstring reads like it was written by an LLM, fix it" → The specific tell identified (significance instead of mechanism — 'provides robust protection against runaway code' names no number or mechanism) and rewritten to state the actual fact ('the VM polls allocator usage every 255 instructions; crossing the hard limit exits the worker with OOM_EXIT_CODE'), plus a scan for industry-metaphor language like 'wired through' or 'surfaces to the caller' replaced with the literal mechanism
New here? 3-minute setup guide → | Already set up? Copy the template below.
# Technical Writing Style
Write prose that reads like human technical documentation rather than LLM output. Applies to docstrings, comments, limitations/caveats sections, READMEs, commit messages, and PR descriptions. The reader is an engineer looking for a fact — give them the fact. You are not persuading or building to a conclusion: say what happens, when, and what it costs.
## Tells to Avoid
### Significance Instead of Mechanism
The most common LLM tell. If a sentence would fit unchanged in any other project's docs, it carries no information.
- ✗ "This ensures the sandbox remains secure."
- ✓ "Every operation runs relative to a `Dir` opened at mount time, so `..` and symlinks cannot reach outside it."
- ✗ "Resource limits provide robust protection against runaway code."
- ✓ "The VM polls allocator usage every 255 instructions; crossing the allocator's hard limit exits the worker with `OOM_EXIT_CODE`."
### Throat-Clearing
Openers that delay the sentence: "It's worth noting that," "It's important to understand," "In essence," "Simply put," "At its core," "Let's take a look at." Delete them — the sentence underneath is the content.
- ✗ "It's worth noting that overlay writes are discarded when the feed ends."
- ✓ "Overlay writes are discarded when the feed ends."
### The "Not Just X, But Y" Reveal
Building to a payoff is an essay move. Docs don't need one.
- ✗ "`heap.rs` isn't just another module — it's the foundation of the entire safety model."
- ✓ "`heap.rs` contains the `unsafe` code that `HeapReader` soundness depends on. Changes need explicit review."
### Adjectives Doing the Work of Facts
"Powerful," "seamless," "robust," "elegant," "blazing fast," "significantly," "dramatically." Replace with a number, a mechanism, or nothing.
- ✗ "Overlays are capped at a reasonable size."
- ✓ "`memory_usage_limit` caps retained overlay data at 100 MB by default; exceeding it raises `MemoryError` in the sandbox."
### Restating What the Reader Can See
A docstring that repeats the signature wastes the line it occupies. Say why it exists, what it costs, or where it bites.
- ✗ "Adds a mount to the mount table." (on `MountTable::mount`)
- ✓ "Opens the host directory once; later operations run against that descriptor, so renaming the path afterwards does not detach the mount."
### Summarizing Yourself
Don't close a section by restating it, and don't announce what the next section will do.
- ✗ "In summary, mounts are confined structurally rather than by checking."
- ✓ (nothing — you already said it)
### War Stories
Provenance is worth a clause only when it changes what the reader does. How the bug was found usually doesn't.
- ✗ "This was demonstrated against a live deployment during an internal red-team exercise, where sandboxed code wrote a module and the client executed it during ordinary result conversion."
- ✓ "Sandboxed code can write a module not yet imported and have the host's next `import` run it, including imports the library makes itself."
## Smoothness — A Different Failure
The tells above pad out empty content. Smoothness dresses up real content, which makes it harder to spot and easier to approve without noticing.
Sentences engineered for rhythm read as conclusions, so the prose sounds like it's arguing when it's only listing facts. Balanced clauses and a stressed last syllable make a sentence sound authoritative whatever it contains — one fact wearing three clauses gets read as three facts. Reference prose usually ends flatly, on a qualifier or a noun phrase, because the writer stopped when the information ran out, not when the cadence resolved.
**Timing for suspense** — commas and subordinate clauses arranged to delay the point:
- ✗ "The sandbox cannot execute what it writes, but your machine will, later, with your privileges, and the path from one to the other is easy to miss."
- ✓ "Files written by sandboxed code stay on the host, where other programs may execute them."
**Telling the reader how to feel** — "you did not choose," "easy to miss," "without being asked," "often does." These supply a mood in place of a fact.
- ✗ "`sys.path[0]` is a directory you did not choose."
- ✓ "`sys.path[0]` is the script's directory, or the cwd for `python -m`, `python -c`, and the REPL."
**Triples and reversals** — a three-item list where one item carries the fact, then a "but" clause positioned as the payoff.
- ✗ "Sandboxed code reads, writes, and deletes normally and sees its own changes, but nothing reaches your disk."
- ✓ "Writes are kept in memory and discarded when the feed ends. Sandboxed code still sees its own writes."
**The quotable closer** — a generalization at the end of a section, memorable, carrying no new fact. Delete it; the section ends at its last fact.
- ✗ "Principles alone produce prose that follows the rules and still reads like an LLM."
- ✗ "Most drafts get better by deleting the first sentence and the last."
**Symmetry for its own sake** — three-item lists where two items are real, paragraphs of matched length, every bullet opening with a bolded term. If the shape came first and the content was fitted to it, cut back to what's true.
**Three checks for smoothness:**
1. Does the sentence end on a beat? If the last three words could be duller without losing meaning, they were there for rhythm.
2. Strip the rhythm and count the facts. One is the usual answer.
3. Is the sentence about the system, or about how the reader should feel?
## Industry Metaphor
Software described as objects moving through space, or as people with intentions, is the register of a startup design review, not reference documentation — well-known reference docs use plain verbs throughout ("raises," "returns," "is stored in," "propagates," "Changed in version X.Y").
The metaphor also deletes the mechanism. "The error surfaces" doesn't say whether it raises, returns, or logs. "Wire the tracker through" doesn't say parameter, field, or global. "It lands in the next release" doesn't say merged or released.
**Motion and logistics:**
| Instead of | Write |
|---|---|
| lands, landing | merged, released in X |
| ship, shipping | release |
| spin up, stand up | start, launch |
| wire up, plumb through | pass, connect |
| thread X through | pass X as a parameter |
| bubble up | propagate, or name the caller |
| surface (verb) | raise, return, report, log |
| hand back, hand off | return, transfer |
| bake in, baked into | built in, compiled in |
| punt on | defer, skip, leave to |
**Structure as furniture:**
| Instead of | Write |
|---|---|
| seam | interface, boundary |
| surface, surface area | API, the public functions |
| escape hatch | override, opt-out |
| knobs, dials | options, settings |
| load-bearing | required, relied on by X |
| X-shaped | with the same interface as X |
| lives in | is defined in, is stored in |
| sits on top of | wraps |
| under the hood | internally |
**Code with intentions:**
| Instead of | Write |
|---|---|
| the checker is happy | the check passes |
| knows about, is aware of | reads, checks, has a field for |
| talks to | sends requests to |
| teach the parser to | add X to the parser |
| wants, expects (of code) | requires |
| reaches into | accesses, reads |
Also avoid: "for free," "just works," "out of the box," "first-class," "table stakes," "opinionated," "non-trivial," "unlock," "blast radius," "paper over."
In prose:
- ✗ "Errors from the worker surface to the caller." → ✓ "`Worker::feed` returns `PoolError::Crashed` when the worker exits without a `FatalError` event."
- ✗ "The tracker is threaded through the whole VM." → ✓ "Every allocation path takes `&ResourceTracker` as a parameter."
- ✗ "`WorkerTransport` is the `NativeSession`-shaped seam." → ✓ "`WorkerTransport` has the same methods as `NativeSession`, so either can be passed where the other is expected."
## Applying This
When reviewing existing prose that reads as smooth, salesy, or generic: identify which tell or metaphor category is responsible, rewrite to name the actual mechanism, and check the three smoothness tests before calling it done. When writing new documentation: state what happens, when it happens, and what it costs — in that order — and stop when the information runs out rather than reaching for a closing line.
Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
A precise, mechanism-first style guide for engineering prose — docstrings, comments, limitations sections, READMEs, commit messages, and PR descriptions — built around one governing rule: the reader is an engineer looking for a fact, so give them the fact instead of building toward a conclusion. Six concrete "tells" each get a named failure mode and a before/after rewrite: stating significance instead of mechanism ("ensures the sandbox remains secure" versus the actual boundary check that makes it true), throat-clearing openers that delay the sentence, the "not just X, but Y" essay-style reveal that reference docs don't need, adjectives standing in for a number or mechanism, docstrings that restate the function signature instead of saying why it exists, and self-summarizing sections that announce what they just said.
Beyond the tells, it names a subtler failure — smoothness — where sentences engineered for rhythm read as authoritative conclusions even when they only restate one fact three ways; a three-check diagnostic (does the sentence end on a rhythmic beat that could be duller without losing meaning? how many actual facts survive stripping the cadence? is the sentence about the system or about how the reader should feel?) catches this in review. It closes with three substitution tables for industry-metaphor language that deletes the actual mechanism — "the error surfaces" doesn't say whether it raises, returns, or logs; "wired through" doesn't say parameter, field, or global — mapping dozens of these phrases (lands, ships, spins up, bubbles up, load-bearing, X-shaped) to the literal, checkable alternative.
Quick Start
Step 1: Create a Project Folder
mkdir tech-writing-style && cd tech-writing-style
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ./
Step 3: Write or Review Docs
claude
Ask Claude to write a docstring, README, or PR description, or to review existing prose that reads as generic or "off." It will apply the tell-avoidance rules and metaphor substitutions, and — when reviewing — name which specific failure mode is present rather than giving vague style feedback.
Tips & Best Practices
- Apply the "significance instead of mechanism" check first when reviewing — it's the single most common tell, and fixing it (replacing a vague benefit claim with the actual boundary, number, or code path) usually improves a passage more than any other single edit.
- Run the three smoothness checks on any paragraph that "reads well" but feels hard to pin down — smooth, confident-sounding prose is exactly the failure mode most likely to get approved without scrutiny.
- Keep the industry-metaphor tables open while reviewing PR descriptions specifically — phrases like "wired through" and "surfaces to" are common enough in casual engineering speech that they slip past without the explicit substitution list as a checklist.
Limitations
- Scoped specifically to technical/engineering prose (docstrings, READMEs, commit messages, PR descriptions) — it's a different register from marketing copy, user-facing help text, or narrative writing, which have their own legitimate use for rhythm and persuasion.
- The before/after examples use a specific codebase's terminology (sandboxes, allocators, worker pools); apply the underlying principle (mechanism over adjective, fact over feeling) rather than the literal examples to a different domain.
- A style discipline, not a technical-accuracy check — prose can pass every rule here and still be factually wrong; pair it with an actual code or documentation review for correctness.