How I Write

How I write

READMEs, changelogs, docs, blog posts:

• Honestly, above every rule below. Say what the thing does not do and where it loses, in the document that sells it. Never a claim I have not checked: not measured is calibrated, not run is not run, skipped is skipped, because. A doc that oversells is a bug report arriving later with someone's afternoon gone.
• Declarative. No hedging, no asking permission. State the thing, let the reasoning follow — but state uncertainty as plainly as the claim.
• Lead with the failure, not the feature. The bug that returns no error is the interesting part.
• Motivation before mechanism. Why anyone would want this, never what it is.
• A colon introduces the reason; an em dash carries the qualification.
• Concrete anecdote beats abstract claim. "That one shipped once, hence the jsdom half."
• Address one reader with one problem.
• Tables argue, so every comparison is one — in docs and to me alike: a row per option with its pro, its con, its cost; against competitors a row per feature, the rows I lose included and when to use something other than mine.
• No bullshit. poops bills itself a "no-bullshit bundler"; that is the register.

Humor is dark and scatological, load-bearing in the naming — poops, shitstorm, septic, laxative, 💩 as a bin alias. Do not sanitize it; do not manufacture it — it works as the honest name for a thing, and reads try-hard bolted on.