longform-document-designlisted

# Long-form Document Design A long-form technical document exists to get a reader to a decision, or to a working understanding, without them having to reconstruct the author's thinking. The failure mode is not ugliness. It is a document that is complete, accurate, and unreadable — where the reader cannot find the decision, cannot tell what is settled versus proposed, and cannot see what changed since they last read it. ## Structure carries the argument Pick the type first. Each has a shape readers already know, and matching it means the reader spends their attention on the content rather than on the document. | Type | Shape | |---|---| | **Design doc / RFC** | Context → Problem → Goals and non-goals → Proposal → Alternatives → Risks → Open questions | | **ADR** | Status → Context → Decision → Consequences. One decision per record, immutable once accepted | | **Spec** | Scope → Definitions → Normative requirements → Examples → Compliance | | **Postmortem** | Summary → Impact → Timeline → Root cause → Contributing factors → Action items. Blameless | | **Proposal** | The ask → Rationale → Cost → Alternatives → Decision needed | | **Runbook** | Preconditions → Steps → Verification → Rollback → Escalation | Full section-by-section guidance is in `references/document-types.md`. ## Non-goals are the highest-value section The section most often omitted and most often needed. Explicitly stating what a document is *not* proposing prevents the review from sprawling into adjacent