AI-Readiness: Documentation as Code

Overview

The last topic of the module, and it closes a loop. Everything in this section depends on something being understandable — by the people maintaining it, and now by the tools working alongside them.

The shift

If AI tools help build and maintain a system, they need to know how it works. They learn that the same way a new engineer does: from the documentation, the code, and whatever context is written down.

So documentation stops being only for humans. It becomes context for machines as well as colleagues.

Conveniently, the qualities that make documentation useful to a model are the same ones that make it useful to a person: current, specific, structured, and explaining why rather than only what. The discipline hasn’t changed. The incentive got stronger, because bad documentation now degrades both your new engineers and your tooling.

Documentation as Code

Documentation as Code means keeping documentation in the repository, beside the code it describes, under the same version control and review as everything else.

Three things follow:

• It changes with the code, in the same commit, reviewed by the same person.
• It’s discoverable — both to a new engineer and to a tool reading the repository.
• Staleness becomes visible. A document nobody has touched in two years is obvious in a way a wiki page isn’t.

Diagrams follow the same rule: written as text and rendered, rather than exported images nobody can edit. A diagram that can only be updated by whoever has the original file is a diagram that will stop being true.

The part that’s genuinely new

Writing why has always been good practice and has always been skipped, because the cost lands now and the benefit lands later on someone else.

What changes is that “someone else” now includes every AI tool anyone on the team uses. A model reading your repository can see what the code does — that’s what code is. What it cannot recover is why the retry logic has that specific backoff, which constraint forced a region split, or what was tried years ago and quietly abandoned.

graph TD
  CODE["<b>The code</b><br/>what the system does"] -->|"readable by anyone"| CLEAR["Clear"]
  DOCS["<b>Written-down reasoning</b><br/>why it does it that way<br/>what was rejected<br/>what constraints forced it"] -->|"only if someone wrote it"| GAP["Otherwise lost"]
  GAP -.->|"costs you twice:<br/>new engineers AND tools"| BOTH["Everyone re-derives<br/>or guesses wrong"]

Code carries the what. Nothing carries the why unless someone writes it down — and now two kinds of reader pay for the gap.

This connects straight back to Domain Authority. The knowledge that makes you valuable is exactly the knowledge that isn’t written down. Writing some of it down doesn’t reduce your value — it’s how the organisation stops depending on single points of human failure, and Module 9 treats it as a practice.

The unglamorous half of readiness

Lintel has no decision records, no architecture documentation worth the name, and a monolith only Ivan Petrov fully understands.

That’s a risk in the ordinary sense — Ivan going on holiday is a problem, Ivan leaving is a crisis. But it’s now also a constraint on the AI platform itself. A system built to answer questions from documentation is limited by documentation quality, and Lintel’s 38% figure assumes docs that are correct and current.

There’s an uncomfortable implication: part of making Lintel AI-ready is unglamorous documentation work with no visible feature attached. Proposing that to Tomas Beck, who has no spare capacity, is a real conversation — and one where the interests-versus-positions framing earns its keep. His position is “no capacity”. His interest is protecting the migration. Documentation that de-risks the monolith serves that interest.

Don’t overcorrect

This does not mean documenting everything. Exhaustive documentation goes stale faster than sparse documentation, and stale documentation is worse than none — it’s confidently wrong, which is the failure mode this whole section keeps warning about.

Write down what’s expensive to rediscover: decisions and their reasoning, constraints and where they came from, and what was tried and rejected. Let the code speak for the rest.

Feeds the workbook

Your charter should say how decisions get recorded. It’s a small line with long consequences — it’s the beginning of a practice the organisation currently doesn’t have.

Check your understanding

1. Name something about a system you work on that a model reading the repository could not recover. What would it cost a newcomer to re-derive?
2. How do you justify unglamorous documentation work to an engineering lead who has no spare capacity? Use their interest, not their position.
3. Why is stale documentation worse than none — and what does that imply about how much to write?

---

→ That’s the module. You have a definition, a way to judge decisions, a read on the people, and a grasp of what has changed. — Module 2 — From Business Need to Requirement

Optional workbook: Exercise 1 turns this module into artifacts. The exercises build on each other, so work them in order or not at all.