What AI documentation misses
AI can write your docs. It can't explain them.
With AI, everyone talks about the speed of code generation. But just like code, generating documentation has never been easier or faster. In a few seconds, AI produces entire pages describing a project. Anyone can quickly generate an overall or detailed technical documentation for a project. This is actually great for onboarding new developers to a project, for instance.
We need to be careful, though.
It doesn’t capture the “why”
Like many people, I believe documentation matters: architecture choices, team standards, the history behind decisions. Documentation is essential for keeping knowledge over time. It automatically gives a snapshot of what exists, but it doesn’t capture the “why”.
Why this architecture and not another? What tradeoff was accepted, in what context, under what constraints? What other options were considered?
None of that lives in the code. It lives in the heads of the people who made the choices or who were in the room. That knowledge doesn’t last and is not captured in automatically generated documentation.
Documentation noise
As it’s easy to use GenAI to generate the documentation, we need to be careful and find the right balance. From documentation that’s thin or missing, to documentation noise where everything is written down but nothing meaningful stands out.
It’s also a pile of documentation that hasn’t been reviewed, hasn’t been taken ownership of, and isn’t being maintained.
Here is my advice: create a skill that engineers can run on demand so they always get the latest version of the documentation. If you save the document, make it clear on what date it was generated and point to the skill so readers can quickly update the documentation.
Documentation has value only if it’s relevant and clarifies the context (the “why”). AI can help write it, structure it, and maintain it. But deciding what deserves to be documented, and keeping the history of what led to each decision, stays a human responsibility.
Source: This article was inspired by https://www.jdecool.fr/blog/2026/07/15/attention-au-bruit-documentaire-genere-par-l-ia.html