Everyone treats documentation as a summary of what exists.
The team writes the code, then writes down what it does. The docs are a record, a reference, a way to remember decisions. They are helpful. They are also wrong.
Documentation is not a summary. It is the boundary that tells you what the system does not do. It is the contract between the system and the people who interact with it. Treating it as a summary makes documentation optional. Treating it as a boundary makes it architectural.
The boundary is the design
Most teams define a system by its features. What it does, how it responds, what it stores. The boundary and what it does not do, what it refuses, what it cannot handle is implicit. Nobody writes it down because nobody thinks of it as a feature.
But the boundary is the most important part of the design. The features define what the system can do. The boundary defines what the system will not do, and that is what determines how people use it, how they trust it, how they build on top of it.
A system without a clear boundary invites overreach. The next engineer assumes that because something works, it is intended. They build on it. It breaks under load. The failure is always "that feature wasn't designed for that." But the real failure is that nobody defined what the feature was for in the first place.
The boundary is what the documentation says the system is, and nothing beyond that. Every undocumented feature is a breach of contract.
Documentation before code
The usual workflow is: write code, write docs. The docs capture what was built.
The discipline of boundary-first documentation flips this: write the docs first, then build what the docs describe. The docs are not a record of the system. They are the system. The code is the implementation.
This does not mean writing fifty pages of spec. It means writing three sentences about what the system does not do.
- What it accepts. Input format, range, edge cases, rejection criteria.
- What it refuses. Behaviors that are possible but not supported, constraints that exist by choice, not by accident.
- What it breaks under. Failure modes the system does not handle, the degradation pattern when it fails, what the caller should do on failure.
That is the boundary. The code that ships should match that boundary. If the code does something the docs do not cover, that is not a feature. It is a scope breach.
The cost of undocumented behavior
Undocumented behavior is not free. It carries interest just like undocumented code.
A function works on input it was not designed for. Nobody documented that, so every caller assumes it is safe. The function breaks under a specific condition that nobody tested for. The bug is a feature collision: two callers used an undocumented capability in incompatible ways.
Undocumented behavior is also a coordination problem. Team A builds on what the code does. Team B documents what the code does. When those two things disagree, Team A's work is wrong and Team B's work is wrong, and nobody knows who to blame.
The fix is not more documentation. It is boundary discipline. If the docs say the system does not handle X, then the code should not handle X. If it does, the docs should say it does, or the code should be removed. Undocumented behavior should not exist.
Documentation as a design constraint
Most teams treat documentation as afterthought. You build the thing, then write about it. This reverses the relationship. The documentation should be a design constraint.
When you write the boundary first, the code becomes easier to write. You know exactly what to implement and what to refuse. You do not build the features that sound nice but are out of scope. You do not add the "just in case" logic that saves you today and costs you next quarter.
When you review code against the boundary, the review is easier. You are not checking that the code works. You are checking that the code matches the docs. If it does something the docs do not cover, that is a bug. Not in the code. In the design. The boundary was unclear, or the implementation went past it.
This is the same discipline as architecture review over code review. You are reviewing the shape of the system, not the lines of code that implement it. Documentation is the artifact that captures that shape in a form other people can read.
What good documentation looks like
It is not verbose. It is not a wiki. It is not a collection of release notes.
Good documentation is short. It names the boundary clearly. It says what the system refuses. It names the failure modes. It is written for the person who inherits the system, not the person who built it.
A one-line summary. What this system does and who it does it for. One line. Not a paragraph. If you cannot fit it in one line, the boundary is unclear.
What it refuses. Three to five behaviors the system does not support. Not the ones that are technically impossible. The ones that are possible by choice. This is the part nobody writes because nobody thinks it matters.
What it breaks under. Three to five failure modes the system does not handle. The degradation pattern. The caller's responsibility on failure.
Who owns it. Not a name. A team. A contact path. A runbook. If the system breaks, who fixes it and how do they find them?
That is documentation as a boundary. It fits on a single page. It takes minutes to write. It prevents months of coordination failure.
The connection to ownership
This is the operational side of ownership as caring about outcomes. When you own a system, you define its boundary. You document what it does not do. You make sure the people who interact with it know the limits.
The engineer who only writes docs after the fact is documenting their own abandonment of responsibility. The engineer who writes the boundary before the code is building the system they want someone else to inherit.
Ownership is not a file path. Documentation is not a record. Both are boundaries that define responsibility.
The one-line version
Documentation is not a record of what exists. It is the boundary that tells you what does not. The system is what the documentation says it is, and nothing beyond that. Every undocumented feature is a breach of contract.