If your code is clean, your documentation doesn’t need to describe it. Anyone who needs to understand the code should read it directly. Anyone who can’t read it won’t need the documentation either, and if your software engineers can’t read the code you’ve got a much bigger problem. In a world of AI coding agents and LLMs, documenting the code is even less relevant, because the LLM is just as capable of absorbing the code as it is the documentation, possibly more so.
Furthermore, to an LLM, the code is the documentation – documentation is just a weak and probably out of date proxy. So, does this mean you don’t need documentation anymore? No, of course not, but it does mean the documentation shouldn’t describe the code. That’s what the code is for.
Any documentation you do produce should describe the why, the where and the how; the reasoning that gave rise to the code. It should describe the intent, the outcomes and the things a person needs to know to make it work.
It should describe the overall ethos and structure. That way, when you give your coding agent a task, you can also give it the context within which it should operate. It will, of course, deviate from that context, frequently and in frustratingly avoidable ways, but at least it will be somewhere close to what you intended.
That’s where the human in the loop comes in. The documentation is a higher level communication that requires a thinking, reasoning intelligence to properly apply what it says. Contrary to the hype, AI agents will never achieve that in their current guise – LLMs and the transformer model lack the basic architect features necessary for the task.
The people developing the current crop of generative AI products know this. Any claims otherwise are pure marketing hype targeted at the gullible, naive and ignorant. AI needs a driver and that driver needs a cognitive framework within which to operate. That framework is referred to as engineering discipline and it goes far beyond just the writing of software or even the building of individual systems. Your understanding of the term “engineer” might be more limited than that, but words have meaning and the term engineer is well defined. (Look it up on Wikipedia).
So, in the AI world, documenting the code is even more pointless than it was before. Hence the line in the Agile Manifesto “Working software over comprehensive documentation”. Don’t, for one second, think that means documentation isn’t needed. It’s just as important as it has always been, but now we can focus on what it should be about. It should describe everything that the code can’t explain.
It should describe all the things that matter to the humans who use, manage, maintain, evolve and own the solutions of which the code is just one tiny, but important part. And yes, LLMs can help you write that documentation, but they can’t possibly know what it is that the writing needs to say
That’s on you.
It always has been, and it always will.