Developer & Tech
Generated Documentation That Does Not Immediately Go Stale
By Jim Vernon, Editor, AI Intelligence International · Published 30 March 2026 · Reviewed against our editorial standards · About the author
Generating documentation is now trivial, which has made a long-standing problem worse: the constraint was never writing the docs, it was keeping them true after the code moved.
This article separates documentation that survives change from documentation that becomes actively harmful, and covers how to generate the first kind.
Key takeaways
- Wrong documentation is worse than none: A missing doc costs a reader ten minutes of reading code.
- Document the why, generate the what: What the code does is derivable from the code and goes stale the moment it changes.
- Docs that live next to the code survive: Documentation in the same file, or the same directory, changes when the code changes because it is in the diff.
- Executable documentation is the strongest kind: Examples that run in CI cannot silently become wrong.
Wrong documentation is worse than none
A missing doc costs a reader ten minutes of reading code. A confidently wrong doc costs an hour and a bad decision, because they trusted it.
This asymmetry should govern what you choose to write down. Anything you cannot commit to maintaining should not exist.
Generated volume makes this worse, because it is now easy to produce far more documentation than any team can keep current.
Document the why, generate the what
What the code does is derivable from the code and goes stale the moment it changes. Why it does it that way is not derivable and does not go stale, because the reasoning was true at the time.
Generated docs are naturally good at the what and incapable of the why, since the reasoning was never in the code.
The productive split: let the tool produce reference material — signatures, parameters, examples — and write the decisions, constraints and rejected alternatives yourself.
Docs that live next to the code survive
Documentation in the same file, or the same directory, changes when the code changes because it is in the diff. Documentation in a separate wiki does not.
Generate doc comments and README files in the repository. Be sceptical of generating anything that lives elsewhere.
Where an external document is required, link to it from the code and date it prominently so readers can judge its age.
Executable documentation is the strongest kind
Examples that run in CI cannot silently become wrong. A doc example that is also a test is the only documentation with a maintenance guarantee.
This is an excellent generation target: ask for usage examples in test form, then wire them in.
Where full execution is impractical, at least type-check the examples. Compilation catches a large share of doc rot.
What generation gets wrong
It describes intent by inference, so it confidently documents what buggy code appears to be trying to do rather than what it does.
It invents plausible parameter descriptions where the name is ambiguous, and those inventions read as authoritative.
It cannot know about constraints outside the file — the caller that depends on ordering, the downstream system that cannot handle nulls. Those are precisely the things worth documenting.
A maintenance rule that holds
Every pull request that changes behaviour must either update the adjacent documentation or state that none exists. One checkbox, enforced in review.
Delete aggressively. A quarterly pass removing documentation nobody has read or updated is more valuable than adding more.
Date everything that cannot be executed. Readers can calibrate trust on age far better than on prose.
Worked example: documenting a service
Starting state: no documentation, eleven modules, two people who understood it.
Generated first: doc comments on every public function and a README with a module map. About forty minutes including review, and roughly a fifth of the generated parameter descriptions needed correction where names were ambiguous.
Written by hand second: a two-page decisions document covering why the queue was chosen, why retries are capped at three, which two approaches were rejected and why. Ninety minutes, and it is the part new joiners actually read.
Generated third: eight runnable usage examples wired into the test suite. Six months later, two of those examples had failed in CI after behaviour changes — which is exactly the point, and neither would have been caught in prose.
Generate the parts that decay, write the parts that matter
Signatures, parameter lists, return types and error tables are mechanical and go stale silently — good candidates for generation from the code itself, regenerated on every release.
Rationale is the opposite. Why this approach was chosen, which alternatives were rejected, and which constraint drove the design cannot be inferred from the code, and a model asked to supply it will produce fluent invention.
Split the document accordingly: a generated reference section and a hand-written rationale section, clearly separated so nobody edits the half that will be overwritten.
Tie regeneration to the build
Documentation drifts because updating it is a separate act of will. Move it into the pipeline: regenerate reference docs when the interface changes, and fail the build if generated docs and source disagree.
Date-stamp every page and show the commit it was generated from. Readers can then judge staleness themselves rather than trusting a page that has silently been wrong for a year.
Review generated prose once before it ships, particularly examples. Generated examples that were never executed are a reliable source of support tickets.
Frequently asked questions
Should every function have a generated doc comment?
No. Comments that restate the signature add noise. Document the non-obvious: units, invariants, ordering requirements, failure behaviour and anything a caller could get wrong.
How do I stop documentation going stale?
Keep it next to the code, make examples executable, and require doc updates in the same pull request as behaviour changes. Nothing else reliably works.
Can AI update existing documentation after a change?
It can propose updates from a diff, which is useful. It cannot know whether the reasoning behind a decision still holds, so the why sections still need a human.
Is an architecture decision record worth the effort?
Yes, and it is one of the few documents that does not rot, because it records a decision at a point in time rather than a current state.
Should generated docs be committed to the repository?
Commit them if humans browse the repo directly; otherwise build them in CI. Either way, never hand-edit generated files.