I made a bet under a deadline once and did not think much of it at the time. The clock, not the theory, chose the approach. Months later I watched a team of full-time architects arrive at the same place deliberately, with time I never had, and treat the documentation not as a description of their work but as the work itself. That is the most satisfying way to be proven right: not by an argument, but by a group of people who had every reason to do it the old way and chose the new one anyway.

I argued in Markdown Is the Knowledge Layer that plain text in git is the format the whole knowledge layer is written in, from a personal second brain up to a company-wide lattice. That post was about the medium. This one is about what happens when a team stops treating that medium as notes about the system and starts treating it as the system’s source of truth. The industry has a name for the discipline. It is docs as code. The part that took me by surprise is how far the good version of it goes.

The constraint picks the method

Here is the honest origin, because it matters. I did not choose to keep architecture in markdown-and-git because I had read a manifesto. I chose it because my binding constraint was time to implementation, and the fastest path to something an agent and a human could both read was a file in a repo I already had. No platform to stand up, no license to procure, no schema review to sit through. A directory, a CLAUDE.md for conventions, and markdown.

When the constraint is speed, you strip a problem to its cheapest honest form, and the cheapest honest form of “where does our shared understanding live” turned out to be the same answer whether you had five minutes or five months. That is the tell of a good pattern. The person with no time and the team with plenty converge on it from opposite directions. I got there by necessity. The architects I watched got there by choice, and arriving at the same file format from those two directions is the strongest evidence I know that the format is not a shortcut. It is the destination.

Docs as code is not new. Docs as the code is the shift

Give credit where it belongs. Docs as code is a discipline the technical-writing community, the Write the Docs crowd chief among them, has practiced for a decade: keep documentation in the same version control as the software, review it in pull requests, lint it, build it in CI, and treat a broken doc build like a broken test. None of that is my idea, and I am not going to pretend otherwise.

The shift I want to name is subtler, and it is what the architecture team made concrete. In classic docs as code, the documentation describes a system that lives somewhere else. The code is the source; the docs trail it. For a platform or architecture group operating well, that relationship inverts. The documentation becomes the source, and a growing share of the running system is generated or governed from it. The C4 model is not a picture drawn after the fact, it is a text definition the diagram is rendered from. The decision record is not a memo, it is the authoritative statement of why a constraint exists, and the guardrail that enforces it points back at that record. The interface is specified in a file, and the client, the mock, and the validation are generated from the spec, so the document cannot drift from the artifact because the artifact is downstream of the document.

That is the sentence I kept turning over while I watched them work. For this team, the documentation was not the thing you wrote when the real work was done. It was the real work, and the software was one of its outputs.

What it looks like when the docs are the deliverable

Concretely, a mature version of this has a few load-bearing parts, and none of them are exotic:

• Architecture as code. The system’s structure lives as text, C4 or a tool like Structurizr or a plain-diagram DSL, so the picture in the review deck and the picture in the repo are the same file. When the design changes, the diff is legible and the diagram redraws itself.
• Decision records as the constraint store. Architecture Decision Records are not archived, they are queried. A new proposal gets checked against the standing set, and the reason a boundary exists is one grep away instead of one retired colleague away.
• Spec-driven generation. The API contract, the data shape, the event schema all live as the source document, and the code around them is generated and validated against it. I made the narrow version of this case in The ERD Is the Floor: the entity model is not a diagram you draw once, it is the floor everything else stands on, and it belongs in text where it can be checked.
• CI as the maintenance engine. A link that no longer resolves, a decision that contradicts another, a diagram that no longer matches its definition, all of it fails a check the same way a failing unit test does. The knowledge layer gets the exact code-review discipline your code already has, because it is sitting in the same pull request.

Put those together and you get something a regulated shop should recognize instantly. Definitions you can diff are definitions you can audit. A control that traces back to a versioned decision record is a control you can show an examiner, with the reasoning attached and the history intact. This is the same argument I made in The Documentation Dividend, now running the other direction: the documentation a team is disciplined enough to keep as code is not overhead paid to compliance, it is the substrate the system and the audit are both built from.

Why a team multiplies it, and I could not

Solo, docs as code is a personal habit with a ceiling. I keep the corpus honest because I am the only author and the only reader who suffers when it rots. That works, and it is exactly the second brain the earlier post described. But it does not compound, because the graph has one contributor.

A team changes the physics. When documentation is the code and everyone commits to it, every architect’s judgment lands as a reviewable, linkable object in the same corpus, and the value is superlinear in the number of authors. One person’s decision record informs the next person’s proposal. A pattern one team captures becomes the default another team inherits. This is the same failure mode I described in Same Question, Different Worlds, solved from the front: shared, captured context is what keeps five capable people from building five divergent things, because they are all reading and writing the same source instead of holding it privately in their heads.

That is what I could not manufacture alone, and it is the part that landed as satisfaction rather than vindication. I had proven the format survived one author under pressure. The team proved the thing I could only assert: that the same format, given more hands that treat it as their code, does not just survive at scale, it gets stronger with every commit.

The honest caveat

I will not pretend the discipline is free, because the reason every knowledge base before this one died is still true. Documentation as code rots exactly as fast as any other documentation the moment the maintenance cost outruns the will to pay it. A team that adopts the ceremony without the enforcement ends up with a prettier graveyard.

Two things keep it alive, and both have to be real. The first is that the maintenance is now genuinely cheap, because a model does the bookkeeping a human always abandoned, the load-bearing insight of the parent post. The second is that the enforcement has to be mechanical, not cultural. A convention people are asked to follow decays. A CI check that fails the build does not. The team I watched did not have better intentions than the teams whose wikis I have seen die. They had a failing check where the others had a good intention, and that is the entire difference between documentation that is the code and documentation that is a museum.

The satisfaction was the point

The idea did not get better when a bigger team adopted it. It got confirmed, which is a different and quieter pleasure. I reached for markdown in git because I had no time to do anything more elaborate, and the thing I did out of necessity turned out to be the thing a group of people with real time and real rigor chose on the merits. When your constraint forces you to the simplest honest answer and the unconstrained experts arrive at the same answer deliberately, you were not cutting a corner. You were finding the shape early.

The knowledge layer was always plain text in git. What the team taught me is the next sentence: once documentation is the code, the discipline of the team writing it is the moat, and no platform sells that. You build it one reviewed commit at a time, and you feel it the day you watch someone else defend it better than you did.

---

The companion read is Markdown Is the Knowledge Layer, which makes the case for the medium. This one is about the discipline that turns the medium into a codebase.

If your team treats documentation as the code, or you are trying to get it there and the enforcement keeps slipping, I want to compare notes. Find me on X @orestesgarcia or LinkedIn /in/setsero.