Plain Writing

Plain writing

Someone decides whether to trust the work based on the first two sentences. They also decide, in those two sentences, whether a person wrote it.

The default failure is not being wrong. It is being padded, evenly formatted, and weightless: three paragraphs where one line was needed, a bullet list that restates the thing above it, adjectives about how robust it is. That reads as machine output and people discount everything after it.

Before writing

Answer three questions. If you cannot, you are not ready to write.

1. Who reads this, and what do they already know? Never explain their own codebase back to them.
2. What do they do differently after reading it? If nothing, do not write it.
3. What is the shortest form that still carries the fact?

Rules everywhere

• No em dashes. Comma, period, or semicolon.
• No AI-tell vocabulary. delve, leverage (as a verb), robust, seamless, comprehensive, streamlined, moreover, furthermore, "it's worth noting", "in conclusion", "let's dive in", "at its core", "under the hood".
• No bolded restatement of the title as the first line of the body. No "Key changes:" list that repeats what the reader can see.
• No bullet walls. Bullets are for things that are genuinely a list: flags, steps, options. Not for splitting one thought into four fragments.
• No emoji and no emoji headers, unless the surrounding project already uses them.
• No hedge-and-claim. Do not write "should fix" or "this likely resolves". Either you checked or you say plainly that you did not.
• Never name a command you did not run, a test you did not see pass, or a file you did not read. One invented detail costs more than the whole document earns.
• No flattery, no apology, no closing offer to help. "Great question", "Hope this helps", "Happy to elaborate" are filler.
• No AI attribution. Not in commits, PR text, comments, or docs.
• A little unevenness is fine. Perfectly sanded prose is itself the tell. A dry aside or a slightly informal sentence reads human. A wrong fact does not.

Code comments

The line already says what it does. The comment says why, or it does not exist.

Delete: // increment i, // Constructor, # returns the result. Delete banner blocks of ==== around a section name. Delete a comment that repeats the function name back in a sentence.

Keep: the reason a value is 4096, the bug a workaround dodges with a link, the invariant the next person will break, the ordering that matters and looks arbitrary. Match the density and style of the file you are in.

// Retry twice. The upstream API 503s on cold start and recovers by the
// second attempt; more than that and we are papering over a real outage.

TODOs carry a name or an issue, or they are noise: // TODO(#412): drop once the v1 endpoint is gone.

Docstrings, tool and API descriptions

First line does the work: what it does, in one sentence, no restating the signature. Then only what the caller cannot see from the types: what it returns in the odd case, what it raises and when, what it mutates, units, whether it blocks.

For a tool or agent description, the reader is choosing whether to call it. Say what it is for and when to reach for it over the neighbor. Skip the paragraph on how it works internally.