Documentation Standards
Comments carry decisions, documents answer one question each, and refusals get written down.
Overview
This document covers what a comment is for, how to split documents so they do not overlap, why a refusal deserves a record more than a feature does, and the specific failure of writing nothing at all.
Why This Exists
Code records what a system does. It cannot record what was considered and rejected, which alternative looked better and why it lost, or what would have to change for the decision to be revisited. That gap has a measurable cost. One project in the family behind AZOTH produced four months and hundreds of commits of original work, recorded none of its reasoning, and went dormant. Everything transferable about it survives only because other projects reconstructed it afterwards, and two of its capabilities were lost entirely and rebuilt weeks later without the refinements the first version had. Its own readme was never edited from the generator's template.
Comments carry decisions, not descriptions
One document, one question
Write down what you did not build
Documentation that stays true
What not to write
Related Principles· 2
Related Documents· 4
Referenced By· 2
Version History
- v0.1.0
Initial structure and metadata established.
- v0.2.0
Written from real experience. Establishes comments as records of decisions rather than descriptions, splitting documents by the question each answers, writing down refusals with their reopening criteria, and what makes documentation stay true. Closes with what not to write.