Docs are fun again
Let’s be honest about the state of internal documentation in most companies: there is none.
Not “outdated”. Not “incomplete”. Absent. Twenty-five years in the industry, and I can count on one hand the teams that had accurate, maintained documentation for their own services. The pattern is always the same: someone writes a wiki page during the initial build, the system evolves for eighteen months, and the wiki page stays frozen in time until everyone silently agrees to ignore it. The few pages that do exist are worse than nothing. They describe a system that no longer exists, which is more dangerous than having no description at all.
This was never a discipline problem. It was an economics problem. And the economics just flipped.
The old excuse is dead
Everyone always agreed documentation was important. Nobody ever funded it.
No company I worked at hired technical writers for internal systems. That role existed for public-facing API docs, maybe, if the company was large enough. For internal services (the payment gateway, the notification pipeline, the authentication layer that three teams depended on), documentation was “the developer’s responsibility”. Which meant it was nobody’s responsibility, because the developer had a sprint to deliver and documentation was never in the acceptance criteria.
A developer who spends an afternoon documenting a service’s retry logic is a developer who did not ship a feature. Management wanted features. Documentation lost every single time.
The tooling trap
Some teams tried to automate the pain away. Tools like Structurizr promised architecture-as-code: define your system in a DSL, get C4 diagrams automatically. The idea was sound: concentrate on the most valuable artefacts and let automation handle them.
In practice, it was a nightmare. The generated diagrams were generic, not tailored to individual services. A simple CRUD service and a complex event-driven pipeline produced the same cookie-cutter output. Developers spent their time on syntax, rendering bugs and layout instead of just drawing the diagram they needed.
A ten-minute Mermaid sketch communicated more than what the tool produced after an hour of configuration.
Structurizr is not a bad tool. The problem with documentation was never a lack of generation tools. Good documentation requires understanding: what matters, what to leave out, how this service differs from that one. Pre-AI automation could parse structure. It could not judge relevance.
AI changes the economics
AI can. An agent that just finished refactoring the payment service can generate accurate, structured documentation of the new flow in minutes. Not a rough draft, but a genuine description of what the code does, how the components interact, what the failure modes are, and how to call the API. The developer reviews, adjusts the parts that need human judgement, and commits.
The cost of creating internal documentation dropped by an order of magnitude. The cost of not having it stayed the same.
When writing docs takes minutes instead of hours, the backlog excuse evaporates. When an agent can update the service docs as a side effect of a code change, staleness stops being inevitable.
Docs that maintain themselves
Writing the docs once is the small part. The real shift is that AI can keep them current.
The pattern works like this: a developer changes a service’s authentication flow. The CI pipeline (or the agent that made the change) detects that the relevant documentation is now out of sync. It generates an updated version, opens a PR, and flags the diff for human review. The documentation tracks the code, not the other way around.
This is not hypothetical. Teams running AI-native workflows already treat documentation as a build artefact. The same agent that writes the code writes the docs. The same review process that catches bad code catches bad docs. Documentation becomes part of the definition of done, as an automated step in the pipeline rather than a manual checklist item.
Documentation that updates itself is not a luxury. It is what happens when you stop treating docs as a separate activity from engineering.
The maintenance problem was always the real problem. First drafts are annoying but manageable. Keeping twenty service docs accurate across hundreds of commits per month was the part no team could sustain. AI sustains it effortlessly.
The context flywheel
Here is where it gets interesting. Documentation written by AI becomes context consumed by AI. A well-documented service is a service that agents can work with reliably.
When an agent needs to integrate with the payment service, it reads the payment service’s documentation. If that documentation is current, structured, and accurate, the agent produces correct integration code. If the documentation is stale or missing, the agent hallucinates: it invents endpoints, guesses schemas and produces code that compiles but fails at runtime.
This creates a flywheel. Better internal docs mean better agent output. Better agent output means faster development. Faster development means more changes, which the AI documents, which keeps the docs current, which makes the next agent interaction better.
Internal documentation is no longer a record of what was built. It is the interface through which agents understand and extend what exists.
The teams that document well compound faster, and discipline has little to do with it. Their agents have better context. Documentation became a multiplier on engineering velocity, not a tax on it.
What good internal docs look like now
The shape of useful internal documentation has not changed much. Structured over narrative: clear headings, explicit API contracts, failure modes, dependencies. Honest over comprehensive: three accurate paragraphs beat thirty stale pages. What changed is who writes them, and how often they get updated.
The best internal documentation reads like a briefing for a senior engineer who already knows how to code but does not know your system.
That is exactly what agent context is. Context engineering is the discipline of designing what information reaches the model, when, and in what structure. It turns out to be the same discipline as writing good internal docs. The skills converged. Documentation written for humans at 2am during an incident is documentation an agent can parse when generating integration code. These are not competing goals.
Documentation is no longer the thing nobody has time for. It is the thing AI has infinite time for — and the thing that makes every other AI interaction better.
The oldest chore in software engineering turned into a self-sustaining loop. AI writes the docs. The docs feed the AI. The system gets smarter with every commit.
Docs are fun again. Not because someone made writing them exciting — but because nobody has to.
Want to build documentation pipelines that keep your internal knowledge current and agent-ready? Let’s talk.