For years, I’ve advocated for keeping developer documentation in the same code repository as the code it describes. In the age of AI, that practice has become even more important.
The reason is simple: the easier we make it to maintain documentation, the more likely it is to stay current.
Reduce the friction
Developers write code in their IDE and manage it in Git. But too often, the accompanying documentation lives somewhere else — Confluence, a wiki, or a separate documentation platform.
Every context switch adds friction. Developers have to leave their workflow, find the right page, make the change, and remember to publish it. It’s no surprise that documentation updates get overlooked.
Keep the docs in the repo, and they become part of the same workflow. Developers can update code and documentation together, in the same branch and pull request.
When documentation toil meets developers where they work, the toil is more likely to be completed instead of avoided. Reduce the barrier to completion, so that it’s nearly as easy to do it as it is to ignore it.
End-user documentation is a different concern. It can be generated or published from the source documentation, giving user-focused polish, accessible content, etc without requiring access to the code.
AI needs context, too
Everything that applies to human developers applies to AI coding agents. But there’s another compelling reason to keep documentation close to the code: documentation gives agents context that the code alone can’t provide.
Code describes what a system does. Documentation explains what it’s supposed to do, why it works that way, and which constraints matter.
Without that context, an agent must infer intent from the implementation. Inferences and assumptions aren’t always correct–and starting with a garbage inference means you get garbage output. With the extra context of documentation, your coding agent has a better foundation for making changes that preserve intended behavior.
More relevant context doesn’t guarantee better code, but it gives agents a better chance of getting it right.
Better context means better reviews
Documentation also gives AI agents another way to evaluate their own work. (You are doing adversarial code reviews when you use a coding agent, right?)
When reviewing a change, an agent can compare the implementation against the documented intent.
- Does the code meet the requirements?
- Does it preserve the expected behavior?
- Has the change introduced a discrepancy between what the system is supposed to do and what it actually does?
Tests and static analysis remain essential, but documentation adds another point of reference — one that can help expose problems neither the code nor the tests make obvious.
Of course, documentation can be wrong, too. Keeping it alongside the code makes it easier to maintain, but we still need to ensure both reflect the intended behavior.
Make documentation part of engineering
AI isn’t eliminating the need for good documentation. It’s increasing its value.
- Keep developer documentation alongside the code.
- Make updates part of the same workflow.
- Update and publish end-user documentation from that source as needed.
Do this for your developers, and you’ll reduce the friction that keeps documentation from getting updated.
Do it for your AI agents, and you’ll give them the context they need to write and review better code.
The principle hasn’t changed. But in the age of AI, the payoff is bigger than ever.
Leave a Reply