AI for documentation: fighting the staleness that makes docs lie

Everyone reaches for AI to write documentation, and it's great at it. Authoring was never the hard part of docs. The hard part is staleness: docs drift from the code, go confidently wrong, and teach the next reader something untrue. Generate a pile of docs fast without fixing drift and you've just made the staleness problem bigger. Here's where AI actually helps, and where it doesn't.

The reframe

Documentation's hard part is keeping it true, not writing it. AI that writes a thousand words of docs in a second still hasn't touched the maintenance half of the job.

A pile of auto-generated docs nobody trusts is worse than a handful that are reliably current. Volume is not the goal; truth over time is.

Where AI genuinely helps

• Docstrings and comments are decent first drafts from code, but push past the obvious. A docstring that says "returns the user" for get_user() is noise. The valuable comment captures why and the gotcha, not the what the code already shows.
• READMEs and getting-started guides: scaffolding for a new project's entry docs, which otherwise never get written.
• On-demand explanation: sometimes the best doc is asking the model to explain the unfamiliar code right now. That beats a written doc that's six months stale.
• Keeping docs in sync is the real win. An agent that updates the docs in the same PR as the code change, or flags doc/code drift, attacks staleness directly. This is where AI earns its place in docs.

The traps

• Restating the obvious. Generated docs love to narrate what the code plainly does. That's noise that buries the few lines of real insight.
• Confident-wrong docs. AI can describe behavior that isn't real. Verify generated docs against the code. Wrong documentation is worse than none because it's trusted.
• Volume mistaken for value. Resist the urge to auto-document everything. Document the non-obvious: intent, contracts, gotchas, the why.

Docs are also agent context

Here's the multiplier: good docs aren't just for humans anymore. Agents read them too. Your CLAUDE.md, your READMEs, your architecture notes are context that makes agents effective. That makes documentation software as memory, and it means keeping docs current pays double: better onboarding for humans and better output from every agent you point at the repo. Stale docs mislead your agents as confidently as they mislead your new hires.

The discipline

• Docs live next to code and get updated as part of the change, not as a separate later task that never happens.
• Capture intent over mechanics: the why, the gotcha, the contract. Let the code speak for the what.
• Let AI make the update cheap. The reason docs go stale is that updating them is friction; AI's best role is removing that friction so the update actually happens every time the code changes.

The honest version: don't use AI to generate a mountain of documentation. Use it to make keeping the important docs true cheap enough that it actually happens, in the same PR, every time. The bottleneck was always maintenance. That's exactly where AI should aim. Get that right and your docs stop lying to your team and to your agents.