As-built documentation records what was actually built, as opposed to what was designed. Construction produces it at the end of every project. Software almost never does, which is why the architecture diagram on your wiki and the system running in production are two different things.
Construction already has the useful term: as-built. Software needs the same distinction between what was planned and what actually exists.
What does as-built mean?
On a construction project, the architect issues design drawings. They show the intent: where the walls go, where the ducts run, where the electrical panel sits.
Then the building gets built, and it deviates. The duct hits a beam and gets rerouted. The electrician moves a panel eighteen inches because of a conflict nobody saw on paper. The owner changes their mind about a door.
Contractors mark up the drawings as these changes happen. At the end, those markups become the as-built drawings: the record of the building that exists. They are what the facilities team uses for the next thirty years. Nobody renovating a hospital wants to know where the duct was supposed to go.
Two documents, two jobs:
| Design drawings | As-built drawings | |
|---|---|---|
| Describes | What was intended | What exists |
| Written | Before construction | During and after |
| Used for | Building it | Operating, fixing and changing it |
| Trusted when | The plan is being executed | Something has gone wrong |
The industry treats the gap between them as normal and manages it on purpose. Handover is not complete without the as-builts.
Why does software have no as-built discipline?
Software has the same gap. It is larger, it opens faster, and nobody names it.
The architecture diagram is the design drawing. Somebody drew it in a design review, probably in Lucidchart or on a whiteboard that got photographed. It was accurate on the day. Then the system got built and deviated, the way every system does. A team added a queue to get past a rate limit. A service was split in two. Someone provisioned an S3 bucket in Terraform for a one-off export and it never went away.
Nobody went back and marked up the drawing. Three reasons, and none of them is laziness.
There is no handover moment. A building has a day when the contractor hands the keys to the owner. Software has no such day. It is never finished, so the as-built is never due.
Drift is continuous. A building deviates during construction and then mostly stops. A codebase deviates every day, forever. A hand-maintained record cannot keep up with a system that changes faster than people can describe it. Teams shipping with AI agents have made this worse; I wrote about it in how to keep on top of AI slop.
The design diagram is easy to find. It is on the wiki. The as-built would take work to produce, so people keep trusting the thing that already exists. That is how you get a data-room diagram that is 18 months stale, which is its own problem and I get into it in technical due diligence when the architecture diagram is 18 months old.
The cost is the same as in construction, only less visible. When something breaks at 2am, the person on call needs the as-built. What they have is the design.
What would software as-built documentation contain?
Take the construction idea and ask what a facilities team would want. For software, it comes down to a short list, and every item has to be derived from the running system and its source, not remembered.
- The deployed topology. Which services, functions, queues and datastores actually exist in the account, and how they connect. Not the ones in the diagram. The ones in the Terraform and the cloud console.
- The real data flows. What data moves where, including the paths nobody planned. The export job someone wrote in a hurry counts.
- Trust boundaries. Where the system crosses from one security context to another, who can call across, and with what permissions.
- Ownership. Who changes each part, inferred from commit history rather than from an org chart.
- Deviations from the design. The valuable bit. A list of places where what is built differs from what was drawn. Construction calls these out on the markup. Software almost never does.
- Provenance. Each statement points to the file, the commit or the resource it came from, so a reader can check it.
Notice what is not on the list: prose about why anything was built that way. That is an architecture decision record, and it is a different document. The as-built says what is there. The ADR says why. You want both and you should not confuse them.
Who asks for it?
More people than you would think, mostly at the worst moment.
Auditors. SOC 2 and ISO 27001 both ask you to show your system and your controls. An auditor does not want your design intent. They want to see what is running and what touches what. If your diagram and your environment disagree, you find out in the audit.
Acquirers. Technical due diligence is an as-built exercise by nature. The buyer is purchasing the thing that exists. A diagram from the data room is a design drawing.
Incident responders. Mid-incident is when the gap costs the most. Nobody wants to read code to learn which service sits behind the load balancer.
New engineers. The first week of a new hire is spent reconstructing the as-built by asking people. It works, and it is why the same three engineers keep getting pulled into onboarding calls.
Security teams. Before a security review can say yes, they need to know the real boundaries. The diagram is a claim. They need the evidence.
How do you produce it?
By hand, once, is how most teams do it. Someone takes a week, walks the account, opens every repository, draws the diagram and writes it up. It is a good document, and it is out of date within a month.
The better approach is the construction one adapted for software. Do not draw the building from memory. Survey it.
- Read the sources of truth. Repositories, infrastructure definitions, CI config, and the deployed environment where you can. Not wikis and not people.
- Generate the as-built from them. This is what automated documentation means in practice: the document is derived from the artifacts, so it describes what exists.
- Regenerate when the system changes. A construction as-built is a snapshot because a building stops changing. A software as-built has to be rebuilt on the event that invalidated it, which is the merge. I cover how in event-driven documentation.
- Diff it against the design. If you do have a design diagram, compare it. The differences are your list of deviations, and they are usually where the risk is.
The code has to be read somewhere, which raises the question every security team asks first. If a vendor does it, the analysis should run inside your own boundary, so the repository is read in place and not cloned out. Zipper Blueprint for Engineering is being designed around that model. It is in early access and not generally available.
Handing a design drawing to the facilities team and calling it done would get you fired in construction. Software does it every week.
Frequently asked
Is as-built documentation the same as a software architecture diagram? No. An architecture diagram is usually a design artifact, drawn to show intent. As-built documentation is derived from the deployed system and its code, and records what exists, including the parts nobody drew.
Do I still need design diagrams if I have as-built documentation? Yes. Design diagrams are for deciding what to build, and you will want to compare them to the as-built afterwards. The gap between the two is useful information. Construction keeps both for the same reason.
How often should the as-built be updated? Whenever the system changes. For code and infrastructure, that means on merge to the default branch. A quarterly refresh produces a document that is wrong for most of the quarter.
Related: Automated documentation: what it actually means · Technical due diligence when the architecture diagram is 18 months old · Event-driven documentation