Using AI to Write Documentation That Actually Gets Read

Documentation is the part of the job developers skip. It is also the part that saves the most time six months later, when a new teammate joins or a client asks how a feature works. AI agents closed that gap for me, but only after I stopped asking for generic docs and started giving them real context.

The Two-Step Prompt That Works

Step one: the agent reads the code and writes a reader's-perspective outline. Not the implementation, the mental model a newcomer needs. What does this module solve? What are the three things a reader must understand before touching it? What is the simplest working example?

Step two: fill the outline with prose. Only after the outline is right. Skipping step one produces the usual 'This function takes a string and returns a string' junk that nobody reads.

A Template I Use

# [Module name]
 
## Why this exists
[One paragraph: the problem and the design choice]
 
## The mental model
[Three bullet points a reader must hold in their head]
 
## Working example
[Ten lines of code that actually run]
 
## Common mistakes
[The three things newcomers get wrong]
 
## Where to go next
[Links to related modules, tests, deeper docs]

This template forces the agent to think like a teacher. Generic prompts produce generic docs.

Measuring Whether Docs Get Read

I watch search queries on my internal wiki and commit authorship. If a module has docs but every new feature on it comes from me, the docs failed. If teammates can extend the module without asking me, the docs worked. Readership, not word count, is the metric.

Keeping Docs Fresh

Every PR that touches a documented module must update the doc in the same commit. I enforce this with a pre-commit hook that flags PRs changing .py files without touching the matching .md. See the pre-commit framework for the hook runner. The agent writes the update; I review it. Same review checklist as code.

Documentation is a shipping discipline, not a phase at the end. AI makes the writing cheaper. It does not make the discipline less important.

The Two Audiences You Are Writing For

Future me is one reader. The other is the teammate I have not hired yet, or the contractor who will take over maintenance. Writing for both forces the docs to stand on their own. Nothing that requires a hallway conversation to understand. The agent is good at this neutrality because it has no shared context to lean on. That constraint improves the docs. Use it deliberately.