Paper 03: Documentation as InfrastructureAuthor: Engineering Team, Binary & Bus, Sys.
Published: 3rd September, 2026
Status: Position Statement
Abstract: Documentation is conventionally treated as a discretionary deliverable, produced after a system is functional and cut first when a schedule slips. This paper argues, on the basis of onboarding data from thirty-one client handovers, that documentation is more accurately modelled as infrastructure with a direct, measurable effect on the cost of a system's second and subsequent engineering team, and proposes a minimal documentation standard sized to be maintained rather than aspired to.
1. Introduction
Every system we take over maintenance of has, at some point, a first team and a second team; the first built it, the second inherits it, whether that second team is external, as in a client handover to our own practice, or internal, as when a single founding engineer is joined by colleagues eighteen months later. The first team's knowledge of why a decision was made, not merely what the decision was, exists almost entirely outside the code, and it does not survive the transition unless it has been deliberately captured. This paper is concerned with what happens when it has not been.
We do not argue for comprehensive documentation as it is often practised: long-form architecture documents produced once, at a project's outset, and left unmaintained thereafter, which in our experience are frequently less useful than no documentation at all, since a stale document that describes a system's abandoned intentions rather than its current behaviour actively misleads the engineer relying on it. Our argument is narrower and directed at a specific failure mode: documentation that is sized beyond what a small team will actually keep current.
2. Methodology
For thirty-one client handovers onboarded by our team between 2023 and 2026, we recorded the state of existing documentation at the point of handover, classified on a four-point scale: none, stale (present but materially inconsistent with current system behaviour on inspection), current but informal (accurate, but uncatalogued — scattered commit messages, chat logs, or a single engineer's memory), and current and structured (a maintained, findable record of system decisions, however brief). We then measured total onboarding hours logged by our team before reaching functional familiarity with the system, defined as the point at which our engineers could make a routine change without needing to consult the original team.
We also recorded, separately, the length of any structured documentation present, in order to test whether documentation volume itself predicted onboarding speed, independent of whether it was current.
3. Results
Documentation state at handover n Median onboarding hours Range --------------------------------------------------------------------------- None 9 41 18-89 Stale 6 52 24-104 Current but informal 9 19 8-38 Current and structured 7 11 4-22
Stale documentation produced worse onboarding outcomes than no documentation at all, though the difference in this sample is within the overlapping range and should be treated as suggestive rather than conclusive; it is nonetheless consistent with the expectation that inaccurate documentation costs the reader time twice, first to read it and again to discover where it is wrong. Current documentation, whether formally structured or not, roughly halved onboarding time relative to its absence. Within the current-and-structured group, document length showed no meaningful correlation with onboarding speed once currency was accounted for; the shortest document in this group, four paragraphs describing why a non-obvious data model choice was made, correlated with one of the fastest onboarding times recorded in the full sample.
4. Discussion
The result that currency matters more than volume, and that volume shows no independent benefit once currency is controlled for, is the basis of our position that documentation should be scoped to what a team will actually maintain rather than to what would be comprehensive in principle. A single-engineer team is not going to maintain a fifty-page architecture document under delivery pressure, and a document that is not maintained decays into the stale category, which our data suggests is actively counterproductive. The correct target size for a small team's documentation is therefore not "complete" but "small enough to survive contact with a deadline," and we treat any documentation practice that fails this test as a liability rather than an asset, however thorough it looked at the moment it was written.
What current documentation in this sample tended to capture, in the successful cases, was not a description of the system's structure — which is recoverable from the code itself by a competent engineer — but the record of decisions that are not recoverable from the code: why an alternative approach was rejected, what constraint a workaround exists to satisfy, which parts of the system are considered stable and which are known to be provisional. This is consistent with treating documentation as a record of intent rather than a description of implementation, since implementation is, by definition, already fully specified by the code that exists.
5. A Minimal Standard
Our internal standard, applied to our own projects and recommended to clients, is a single living document per system recording: the reason for each non-obvious architectural decision, in a sentence or two, at the time it is made; explicit note of any deliberately deferred or rejected alternative; and a dated list of known provisional components not yet considered final. This is deliberately far short of comprehensive and is sized to be updated in minutes as part of the change it documents, not scheduled as separate work to be done later.
6. Conclusion
Documentation should be evaluated as a form of infrastructure with a direct effect on the cost of a system's next maintainer, and sized against the standard of what a given team will actually sustain, not against an ideal of completeness that predictably lapses into the stale state our data associates with the worst onboarding outcomes we recorded. A short, current record outperforms a long, aging one, and this is the standard we hold our own engagements to.