how-i-writelisted

# 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.