Engineering documentation is the deliverable in its own right when the next person who has to act on the system is not the person who built it. That single condition decides the question. It is not about thoroughness, not about discipline, not about what a mature engineering culture is supposed to look like. It is about whether the next consequential reader can act without the original author in the room. If they can, the system is documented enough. If they cannot, the system is not documented at all, regardless of what is in the repository.
Most systems are undocumented for the same quiet reason. Nobody decided whose job it was. The engineer who wrote the code was paid to write the code. The engineer who reviewed it was paid to review it. The product manager who scoped it was paid to scope it. None of them were paid to write the document the next person — six months from now, eighteen months from now, after a team change or a vendor change or an acquisition — would need in order to act without rebuilding the reasoning from a Slack archive. So no document was written. The system did its job. The reasoning evaporated. By the time someone needs the document, the people who could have written it cheaply have moved on.
The studio's view is that this is not a failure of discipline. It is a failure of scoping. Documentation, where it actually matters, is a deliverable. It is contracted for, named in the engagement letter, owned by a person, and shipped on a date. When it is treated as something the team should "also do," it does not get done — not because engineers are lazy, but because the work to do it well is real work, and real work that is not on anyone's plate does not happen.
The cases where the document is the work
Three cases come up repeatedly where the document is, properly, the deliverable rather than a side artefact.
The first is the architectural decision that will harden in production and outlive the team that made it. The choice of message bus, the choice of vector store, the choice between an internal and an external authentication provider, the choice to serialise events one way rather than another — these decisions are easy to make and expensive to revisit. A short written record of the option chosen, the options declined, the conditions under which the team would re-open the decision, and the named person who owns the next review is worth more, two years downstream, than the working code. The code can be rebuilt. The reasoning, once lost, cannot be reconstructed from the code alone.
The second is the handover that is going to happen whether anyone has scheduled it or not. A founding engineer leaves. A vendor is replaced. A team is reorganised. An acquisition closes and the parent company's engineering function inherits a system it did not build. The work that determines whether this transition is recoverable in a fortnight or unrecoverable for a quarter is almost entirely the work of writing the system down before the handover, by the person who still has the knowledge in their head. The studio has watched the same shape of failure several times — a competent successor team, a working system, no document, three months of archaeology, a quietly-revised roadmap. The cheapest hour available, in retrospect, was always the hour the original author would have spent writing.
The third is the system that has to be defended to a reader the team cannot fully predict. A regulator. A diligence team. A board. An insurer. An external auditor in the year the company is preparing to be sold. The team has, by then, been operating the system competently for years. The reader is going to ask why decisions were made the way they were. If the answer lives in the heads of three engineers, the answer is, for the purposes of the room, unavailable. A short, defensible, written record changes the conversation. Its absence costs the company time it cannot make up.
What a useful document actually contains
The studio has a small and stable view of what a system document needs to contain to be worth writing. It is not a wiki. It is not a comprehensive technical reference. It is a memo, written in English, that the next senior engineer can read in twenty minutes and act on the same afternoon.
It contains the shape of the system, drawn once. The data flow, named. The boundaries between what the team owns and what it depends on. The decisions that were made deliberately — and the alternatives that were considered and declined, with the reason. The conditions under which the team would re-open each decision. The known failure modes, named, with the response for each. The contact, in the team or formerly in the team, who can answer the question the document does not.
A system document is finished when the next reader can act without calling the author.
What the document does not contain is also part of the discipline. It does not contain code. It does not contain step-by-step setup instructions, which belong in the repository. It does not contain commentary on the team. It does not contain marketing language. It does not contain anything the team would not want to read aloud in the room where the system is being defended. If a sentence cannot survive that test, it is the wrong sentence.
When to stop
Documentation has a stopping condition, and the studio thinks the stopping condition is what most teams get wrong. The condition is not "until everything is written down." That standard guarantees the document is never finished, never owned, and never read. The condition is the one above — the next consequential reader can act without the original author in the room. The moment that condition is met, the document is done. Further writing is a separate engagement, not the same one.
The studio's preference, when the document is the deliverable, is to scope it as such. A named owner. A short timeline, usually one to three weeks for an existing system. A defined reader — the named successor, the named diligence team, the named regulator — whose ability to act on the document is the acceptance criterion. A written acceptance test the team can run before the engagement closes. And then the engagement closes. Documentation that is treated as ongoing is documentation that is treated as nobody's, and documentation that is nobody's is the documentation that does not exist when it is needed.
We will sometimes decline an engagement on these terms — when the reader the document is meant to serve has not been named, when the owner of the document after delivery has not been agreed, when the team wants the artefact but has not decided what acting on it means. The decline is not a judgement on the team. It is a refusal to deliver a document that, six months from now, will sit unopened. The studio prefers to write fewer documents that are read than more documents that are not.