Documentation

Required

• Get a new person running with one command

  Required

  Start the README with what the project does in one sentence, then one command that installs and runs it from a clean checkout.

• Change the docs in the same pull request

  Required

  Keep docs in the repository next to the code they describe, and update them in the pull request that changes the behaviour.

• Generate reference docs from the code

  Required

  Build reference docs for every public interface from the code or contract, never by hand.

• Test the docs in the build

  Required

  Check every link in the docs and run every code sample as a test in CI.

• State each value in one document and link to it

  Required

  Write each limit, time or threshold, such as a session length or a retry count, in one document only. Every other document links there.

Recommended

• Keep decision records with a status

  Recommended

  Number each decision record, give it a status, and replace it with a new record instead of editing it once accepted.

• Keep runbooks next to the code they run

  Recommended

  Write a runbook in the repository for every task a person does by hand in production. Turn each step into a script when you can.

• Keep a changelog written for users

  Recommended

  Keep a dated changelog that tells users what changed for them in each release, written in their words.

• Draw diagrams as code

  Recommended

  Write diagrams as text in the repository, with a diagram language such as Mermaid, PlantUML or D2, never only as an exported image.

• Give every doc an owner and a review date

  Recommended

  Give every guide and runbook an owner and a last-reviewed date, and flag any doc not reviewed in 6 months.