Writing Style

Writing style

Applies to prose written in this repo: docstrings, comments, limitations/, READMEs, commit messages, PR descriptions, and warnings like the one on MountDir.

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 do not 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."

Summarising yourself

Do not close a section by restating it, and do not 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 does not.

• ✗ "This was demonstrated against a live deployment during Hack Monty, where sandboxed code wrote dataclasses.py and the client executed it during ordinary result conversion."
• ✓ "Sandboxed code can write json.py into a read-write mount, or any module not yet imported, and have the host's next import run it, including imports pydantic_monty makes itself."

Smoothness

A different failure from the tells above. Those pad out empty content; this dresses up real content, which makes it harder to spot and easier to approve.

Sentences engineered for rhythm read as conclusions, so the prose sounds like it is arguing when it is only listing facts. Balanced clauses and a stressed last syllable make a sentence sound authoritative whatever it contains, so 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 rather than 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 generalisation 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 is true.

Three checks:

• Does the sentence end on a beat? If the last three words could be duller without losing meaning, they were there for rhythm.
• Strip the rhythm and count the facts. One is the usual answer.
• 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. It is the register of a startup design review, not of reference documentation; CPython's docs use plain verbs throughout ("raises", "returns", "is stored in", "propagates", "Changed in version 3.11").

The metaphor also deletes the mechanism. "The error surfaces" does not say whether it raises, returns or logs. "Wire the tracker through" does not say parameter, field or global. "It lands in 3.14" does not say merged or released.

Motion and logistics:

Structure as furniture:

Code with intentions:

Also: "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."

• ✓ "Checkout::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 session.ts drives either one."

Terms of art stay, even though they began as metaphors: heap, stack, pointer, hot path, propagate, boilerplate, tombstone, sandbox escape, attack surface. CLAUDE.md also sanctions foot-gun, happy path and single source of truth. The test is whether a plain verb would say more than the metaphor does.