Generating Documentation with AI
Posted on: 2026-07-13
I will argue that generating documentation with AI is useful, specifically the kind that lives as dedicated documentation files in folders alongside the code, and specifically for business logic and architecture. My thesis is that this documentation is valuable because it serves humans and AI agents at the same time, keeps a human in the loop where judgment matters, and stays trustworthy only when it is transparent about being generated and organized by explicit rules. I will confront two counterarguments separately. The first is that we could skip the stored documentation entirely and just ask the AI to extract the reasoning from the code on demand. The second is that documentation should not exist as its own files at all, because the "why" could simply live in the code as comments.
Documentation has always been the first thing to decay. Code changes, deadlines arrive, and the reasoning behind a system stays locked in the heads of a few people who happened to be in the room. The most valuable documentation is rarely about syntax or the shape of a function. It is about business logic and architecture, the "why" behind a decision and the flow that ties different pieces together. This is exactly where I found AI to be a strong fit. Instead of asking a large language model to invent facts, I ask it to read the code and the existing context, then write down the business rules and the architectural relationships it observes into documentation files that live in folders next to the code. The result is documentation that finally keeps up with the code.
For humans, this changes the experience of working in a code base. When someone opens a module, they no longer have to reverse-engineer intent from a hundred small commits. They get prose around the business logic that explains the reasoning, the constraints, and the tradeoffs that shaped the current design. That text is not a replacement for reading the code, but it lowers the cost of understanding it. A new engineer can grasp the architecture in minutes, and an experienced one can quickly confirm whether their mental model still matches reality. Writing this by hand was always the part everyone skipped, and now it is generated as a natural byproduct of the work.
The same documentation serves a second audience that did not exist a few years ago: the AI agents themselves. When an agent has to modify a system, it works far better when it can read a clear description of the business logic and how components relate, rather than inferring everything from scratch every time. Good generated documentation becomes shared context that both humans and agents rely on. It is also the mechanism that brings a human back into the loop. When an agent surfaces a decision that needs judgment, the documentation gives the human enough grounding to step in, understand the situation quickly, and make the call without having to rebuild the entire picture from memory.
The first counterargument is that all of this is unnecessary because the reasoning can be extracted from the code on demand. And to be fair, that is a good practice on its own. We have done exactly that, pointing an agent at a code base and asking it to explain the business logic, and it works. So why not simply do that every time and skip the stored documentation altogether? If the code is the source of truth, generating a separate artifact looks like duplication that will drift out of date, the very problem I claimed to solve.
I do not think that objection holds, for three reasons. First, re-deriving intent from the code on every request is slower and more expensive. It burns context and tokens each time, and it forces the model to guess the "why" that the source often does not contain at all. Second, it is not reproducible. Two runs on the same code can produce two different explanations, which is the opposite of what documentation is supposed to give you. Third, extraction only answers "what does this do," while written documentation answers "what is this supposed to do and why." Generating it once and committing it turns that reasoning into a stable, reviewable artifact. A human can correct it, the correction sticks, and afterward both people and agents read the same agreed-upon version instead of a fresh interpretation each time. Extraction is a good way to produce that first draft; the mistake is throwing the result away instead of keeping it. The drift concern is real, but the answer is to regenerate deliberately, not to give up on having a record at all.
The second counterargument says documentation should not exist as separate files, because the "why" belongs directly in the code as comments. I agree with this view. A comment sitting next to a strange conditional or an unusual workaround is often the fastest way to warn the next reader why the obvious approach was avoided, and I am not arguing against comments at all. The problem is that comments are atomic. They explain one line, one function, one branch, but they cannot step back and describe how a dozen modules cooperate to satisfy a business rule, or why the architecture is shaped the way it is. The high-level reasoning ends up scattered across hundreds of local notes and never assembled into a coherent picture. So this counterargument fails not because comments are wrong, but because they operate at the wrong altitude. Documentation files in folders exist precisely to hold the system-wide story. I treat the two as complementary: comments for the local "why," documentation files for the reasoning that spans the whole system.
Both counterarguments answered, my defense still rests on one condition, which is my next point: the whole thing implies generation by AI and organized by the rules added to the repository, not written by hand and not passed off as a human artifact. The AI rules define what gets documented, how it is structured, and what level of detail to include, so the output is consistent and predictable rather than a random summary. Readers know the provenance of what they are reading, and they know that the structure reflects deliberate rules rather than the mood of a model on a given day. That honesty is what makes the documentation trustworthy instead of merely plausible.
So, to return to the thesis, the tradeoff is straightforward. Generated documentation is only as good as the rules that shape it, so those rules have to be maintained like any other part of the system. I also have to acknowledge the honest cost of this approach: it effectively forces the developer to always use AI to keep the code and the documentation in sync. Once the documentation is generated rather than handwritten, updating the code means regenerating the documentation through the same AI process, otherwise the two drift apart. That is a real dependency, and it only makes sense if you have already accepted AI as a permanent part of the workflow. In exchange, I get living documentation of the business logic and architecture that helps humans, feeds AI, keeps a human in the loop where it counts, and survives being asked twice, all while being honest about how it was produced. That is more than on-demand extraction can offer, and more than comments alone can hold, and for me it has been well worth the small ongoing cost.
Discussion
Replies are loaded from the public Mastodon thread for this article.
Loading replies from Mastodon...