readme-writing

README Writing

A README is the mental model someone needs before they touch or adopt the thing it describes. One that only lists files is worse than none: it leaves the reader believing they understand something they do not, and they act on that belief.

Three things hold for every README, whatever it documents, and are stated here once rather than repeated per case:

• Every tree is annotated. One line per entry, giving the reason that entry exists. A bare tree adds nothing over ls.
• Every link is relative. An absolute link points at one host, one account, one branch; it breaks in a clone, in a fork, and on every branch it was not written on.
• Every flow is plain text -- numbered steps and simple -> arrows in a code block. Never mermaid, never any format that must be rendered to be read. A rendered diagram can only be verified by looking at it rendered, which needs a tool that may not be installed; one shipped recently that nobody could validate for exactly that reason. Plain text reads identically on the web, in a terminal, and in a diff, so what is in the file is what the reader sees.
• The concreteness test in Step 3 is the same test for all three cases below.

Step 1: Name the gate

This comes first because it decides everything after it. Three READMEs, three readers, three questions the reader arrives with:

The root of a client's Terraform repo, a service, a library, a CLI -- all one gate: repository root. A folder inside a repo that holds one kind of thing -- migrations/, modules/, components/, services/, agents/ -- is the second gate. A README that travels inside generated output, into a repo its author will never see again, is the third.