Writing Docs

Overview

A doc whose job is to track the repo is a set of claims that must be true of the repo. This is the spine: when any guideline conflicts with verifiability, verifiability wins. A smaller all-true doc beats a complete one with unverifiable parts.

Every assertion unit has one of the document model's four assertion classes:

• Factual — commands, paths, symbols, behavior (output included), structure, values. Must be mechanically checkable against current evidence.
• Normative — instructions and rules. Must name or sit under a current governing source, or record the current owner's judgment.
• Rationale — the "why", tradeoffs, rejected alternatives. Must be marked and coherent with current evidence from a governing decision or implementation source.
• Non-assertive — connective prose or signposting. It carries no truth judgment, and is the only class that does not.