Technical documentation is always outdated — AI can regenerate it continuously if you frame the process
In most software projects, documentation is either nonexistent or outdated by the next sprint. Developers hate writing it, and automatic generation tools often produce generic or even wrong content. Yet generative AI now offers a viable approach: generate the docs from the source code, validate them automatically against the types and tests, and update them continuously in the CI. The result: docs always in sync with the code, produced in 10% of the usual time.
The problem
Technical documentation is a universal software engineering problem. According to the Stack Overflow 2024 survey, 72% of developers consider insufficient documentation to be the main obstacle to productivity on a new project.
The causes are structural: writing docs is not rewarded in sprints, they become outdated as soon as the code evolves, and nobody wants to maintain a document that nobody reads. The vicious circle sets in: the docs are poor, so nobody consults them, so nobody maintains them, so they get worse.
A developer loses several hours per week because of insufficient documentation
It is estimated that a developer commonly loses the equivalent of 5 to 6 hours per week because of lacking documentation. For a team of 10 developers at 70k€/year, that represents a hidden cost of around 150,000€ per year in time wasted looking for answers in the code rather than in the docs.
Generative AI seemed to be the silver bullet: "ask ChatGPT to document your code." But without guardrails, the results are worse than having no documentation. An invented parameter, a code example that does not compile, a description that contradicts the real behavior — and trust in the docs collapses for good.
The challenge is to find the right balance: leverage the speed of AI generation while guaranteeing that every line of documentation is verifiable and verified.
The AI solution
Reliable AI-generated technical documentation rests on three complementary mechanisms that form a trust pipeline.
Generation from types and signatures
Instead of asking the AI to "document this file", give it the TypeScript types, the interfaces, the database schemas and the function signatures. The AI then produces documentation constrained by the types, which eliminates 80% of hallucinations on parameters and return values. The result is reliable API docs in seconds.
Automatic validation against the code
Every code example in the documentation is extracted and run automatically in the CI (doctests). Every documented parameter is checked against the real types. Every documented API endpoint is compared with the real route. This validation pipeline catches 95% of errors before publication.
Continuous updates in CI/CD
On every merge, a job compares the code diff with the relevant documentation sections. If a function signature changes, the matching docs are automatically regenerated and submitted as a PR for review. The developer only has to validate — the docs never fall behind the code.
Implementation
Here is the workflow we deploy at our clients to go from absent documentation to living docs in three steps.
Initial generation: the catch-up docs
Start with the most critical and least documented modules. Use Claude Code to analyze each source file and generate the documentation in batch:
$ claude "Analyze all files in src/api/routes/.
For each route, generate JSDoc documentation
including: description, parameters with types, return value,
possible error codes, and a curl call example.
Base yourself only on the code and types — invent nothing."Review each generated file. Count 2 minutes of review per file, versus 15 minutes of manual writing.
Validation pipeline in the CI
Add a job to your CI (GitHub Actions, GitLab CI) that runs three checks on every PR: the code examples compile and run (doctests), the documented types match the real types (AST comparison), and no public function is undocumented (doc coverage). Tools like typedoc for TypeScript or Sphinx for Python automate these checks.
Continuous post-merge updates
Configure a post-merge hook that detects the modified files, identifies the associated doc sections, and automatically creates an update PR. The developer who modified the code receives a PR with the doc changes suggested by the AI — they validate or correct it in a few minutes. Result: the docs are never more than one merge behind. Discover our Augmented Code Sprint to set up this pipeline.
Results
Frequently asked questions
Does AI generate documentation that is 100% reliable?
No. LLMs produce plausible text, not necessarily accurate text. On technical documentation, the error rate ranges between 15 and 40% depending on code complexity. The most frequent errors: invented parameters, incorrect return values, code examples that do not compile. A validation workflow is essential.
How do you keep documentation up to date after the initial generation?
Integrate doc generation into your CI/CD. On every merge to the main branch, a script compares the code diff with the existing docs and flags potentially outdated sections. A developer validates the updates in 10 minutes instead of rewriting the docs by hand.
Which types of documentation does AI generate best?
API documentation (parameters, returns, examples) is the most reliable use case because the AI can rely on types and signatures. Architecture documentation and contribution guides are riskier because they require an understanding of the business context that the AI does not have.
For technical profiles
Comparison of AI-assisted documentation tools (June 2025):
| Criterion | Claude Code | Mintlify | Copilot Doc | Swimm |
|---|---|---|---|---|
| Generation from code | Whole repo | Whole repo | Active file | Whole repo |
| Automatic validation | Scriptable (CI) | Partial | No | Yes (auto-sync) |
| Continuous updates | Via CI hooks | Manual | No | Auto-detect |
| Output formats | All (MD, JSDoc, RST) | MDX, OpenAPI | Inline comments | Proprietary MD |
| Cost | ~$100/month | $150/month | $19/month | $99/month |
Architecture of the continuous documentation pipeline:
PR merged to main
→ GitHub Action triggers the "doc-sync" job
→ Detection of modified files (git diff)
→ For each modified file:
→ Extraction of types/signatures (ts-morph / AST)
→ Comparison with the existing docs
→ If divergence: regeneration via Claude API
→ Run doctests on the code examples
→ Creation of a "docs: update [module]" PR
→ Slack notification to the tech lead for reviewMetrics to track: documentation coverage (% of public functions documented), doctest validation rate (target: 100%), average review time of generated docs (< 5 min per PR), number of Slack questions resolved by the docs (target: +50%).