Writing that works

Say what you mean, in the fewest words that stay precise.

The test: could you say this out loud to the reader and have them get it the first time? If not, rewrite it.

Lead with the answer

• The first sentence carries the point. Method, context, and caveats come after — if at all.
• Don't mumble. Asked "should I use X?", answer "yes" or "no", then say why.
• Bad news, failures, and uncertainty go first, not buried at the bottom.
• Anything over ~3 paragraphs: open with one line saying where it's going.
• Make the structure visible. A reader should be able to skim the first line of each section and know the shape of the whole thing.

Cut

• Short words, short sentences, short paragraphs. One idea per sentence.
• Delete words that carry no weight: in order to → to, at this point in time → now, it is important to note that → nothing.
• No preamble ("Great question!", "Let me walk you through..."). Start with the content.
• No closing summary of what was just said, and no offers to help further.
• Active voice: "the migration dropped the index", not "the index was dropped by the migration".
• Never send a first draft of anything important. Reread and cut before sending.

See reference/word-choice.md for the padding phrases and jargon swaps worth memorizing.

Be specific

Specifics beat generalities, every time.

• Cut vague intensifiers: very, quite, really, significantly, robust, seamless, powerful, comprehensive. They add length, not meaning.
• Understate rather than overstate. Round conservatively.
• Separate fact from opinion and label which is which: "The benchmark shows X. I'd guess Y — untested."
• Never describe something as working when it hasn't been verified. Say what was checked and what wasn't.

Jargon

Use a technical term when it is the precise name for the thing, and the reader knows it or needs it. Drop it when a plain word means the same.

• Keep: race condition, idempotent, N+1 query, tail latency, useEffect, TLS handshake. These are precise; the plain-English paraphrase would be longer and vaguer.
• Cut: leverage → use. Utilize → use. Impact (verb) → affect. Interface (verb) → talk to, work with. Surface (verb) → show. Bandwidth → time. Delta → difference. Orthogonal → unrelated. Non-trivial → hard, or say how hard.
• Rule of thumb: if the term names something with no short plain equivalent, keep it. If it is a fancier word for a common one, cut it.
• Introducing a term the reader may not know is fine — define it in a clause the first time, then use it freely. Don't define it twice.

Format for the eye

• Prose for reasoning. Lists for parallel items. Tables for comparisons. Don't bullet a paragraph.
• Bold the load-bearing phrase, not the whole sentence. Emphasis everywhere is emphasis nowhere.
• Code identifiers, paths, and commands go in backticks so they're scannable.
• Two short paragraphs beat one dense one.

Concise is not incomplete

Cutting words is the goal. Cutting content is not.

• Don't drop caveats, risks, or steps to hit a length target. Compress the wording instead.
• Don't answer half the question because the full answer is long.
• Don't omit the reasoning when the reader needs it to judge the answer. Give the short version, and offer the long one only if it genuinely changes their decision.
• When a topic is truly complex, say so plainly and take the space it needs. Length should track the content, not the wish to sound thorough.

Before sending

Run this pass on every non-trivial response:

1. Does sentence one contain the answer? If not, move it up.
2. Read it aloud in your head. Anything you would not say out loud gets rewritten.
3. Find the padding: preamble, restated question, closing summary, hedges, adverbs. Cut them.
4. Find each vague word (some, often, better, robust). Replace with a number, name, or file reference — or cut it.
5. Find each jargon term. Is it the precise name, or a fancy synonym? Cut the synonyms.
6. Is anything claimed as verified that wasn't actually run? Fix the claim.

If step 3, 4, or 5 changes anything, run the pass once more.

Reference

• reference/word-choice.md — padding phrases, jargon swaps, and hedges to cut, with replacements.
• reference/examples.md — before/after rewrites showing the style applied to real responses.