Documentation as a Deliverable
Undocumented code and data are only half delivered; the record of what something does and why is part of the work, not an extra.
Documentation Is Part of the Product
A result no one else can understand, run, or extend is incompletely delivered. Documentation, the written record of what a thing does, how to use it, and why it was built that way, is a deliverable in its own right. Treating it as optional cleanup guarantees it will be skipped, and the work will decay into something only its author can operate, until they too forget.
Kinds of Documentation
- Usage: how to run the code and interpret its outputs.
- Interface: what each function or input means, in what units.
- Rationale: why key design and modeling choices were made.
- Assumptions and limits: where the method is valid and where it is not.
- Provenance: how a specific result was produced.
The Rationale Is the Rarest and Most Valuable
Code shows what it does; only documentation captures why. Six months later the author, and certainly anyone else, will not remember why a threshold was set, an approximation chosen, or a term dropped. Recording rationale is what lets future maintainers change the code safely instead of fearing to touch it.
Documentation Rots
Documentation that drifts from the code it describes is worse than none, because it misleads. The defense is to keep documentation close to what it describes, update it in the same change, and, where possible, test examples so they cannot silently go stale. Documentation, like code, needs maintenance.
In Scientific Work
For a program whose claims must be defensible, documentation of assumptions, valid ranges, and provenance is not courtesy but evidence. Kronos design records state which effects a model includes, the conditions under which a number holds, and how it was produced, so a reader can judge the claim rather than take it on faith.