How to write and maintain documentation with AI agents

The README says the app talks to three services. It talks to seven.

Nobody lied. That paragraph was true in March, and then four months of shipping happened around it. It's still the first thing every new person reads, and it's teaching them a system that no longer exists.

Coding agents look like the obvious fix. They read fast, they write fluently, and they never find documentation boring. They're also the reason a lot of projects now have more docs and less trust in them.

What agents get wrong about docs

Two failure modes, and they're different problems.

They narrate. Ask for docs on a module and you get a paragraph per function restating the code in English. createInvoice creates an invoice. Technically accurate, completely useless: anyone who can read the doc can read the function. What the reader needed was why invoices are created in two passes, and what breaks if you merge them.

They fill gaps. An agent documents what it can see, and what it can see is the repo. Not the outage that made the retry limit three, or the customer who needed the CSV export. So it infers something plausible and writes it in the same confident voice as the parts it verified: the same failure mode as invented function names, except a wrong doc survives for years, because nothing fails when prose is wrong.

Code has a compiler. Documentation doesn't. That asymmetry is the whole problem.

The docs agents are genuinely good at

Here's the honest split: agents are excellent at documentation that is derivable: the answer is already in the repo and the work is finding it, ordering it and phrasing it well.

• Setup and "how do I run this": the highest-value page in most projects, and the one nobody maintains.
• API and endpoint reference: routes, parameters, response shapes, error codes. Mechanical, tedious, exactly right.
• Architecture tours: where a request goes, which module owns what. Same work as mapping an unfamiliar codebase, pointed outward at the next person instead of inward at yourself.
• Release notes from a commit range, and upgrade notes from a diff: what changed and what callers must do about it.

What stays yours is the why. Decision records, rejected options, the tradeoff you'd make differently today. An agent can format one beautifully and still not know the argument that produced it.

Make the agent verify, not describe

One change improves doc quality more than any amount of prompt wording: make the claims checkable.

• Have it run the README. On a clean checkout, execute every command in order and fix whatever breaks. It's the best documentation task there is: it turns prose into something that either works or doesn't.
• Ask for receipts. "Cite the file and line for every claim." A statement with a path attached is one you can verify in seconds, and agents invent noticeably less when they know they have to show where something came from.
• Give it permission to not know. "If it isn't in the repo, write TODO; don't infer." Agents fabricate partly because a gap reads to them as failure. Say a gap is an acceptable answer and you get an honest map with holes instead of a complete-looking fiction.
• Test it on a stranger. Fresh session, only the new doc, ask it to do what the doc describes. Wherever it gets stuck is the paragraph you'd have ended up explaining in person.

The real work is drift, not the first draft

Writing the docs is an afternoon. Keeping them true is forever, and that's the half that actually fails.

Two habits cover most of it.

Attach docs to the change that caused them. The doc update belongs in the same task as the code: same brief, same review, same commit. A follow-up card called "update the docs" is a card that quietly ages.

Sweep on a schedule. Once a week, point an agent at the last week of commits and ask one question: what changed that the docs still describe the old way? Small, repetitive, high value: exactly the shape of work worth automating.

Where SanuDesk fits

Documentation loses to features because both compete for the same attention, and features win every time. The fix isn't discipline; it's running doc work somewhere other than your foreground.

SanuDesk is a desktop app that runs Claude Code, Codex and Gemini sessions tiled side by side in one grid, with a Kanban board the agents work from. Doc work gets its own cards, like verify the README or document the billing flow, and a session launched from a card starts with the brief already written, not retyped into a terminal.

Loops cover the drift half. A Loop is a recurring job on a schedule, so "check this week's commits against the docs" happens every Friday whether you remember or not, and arrives as something to review rather than a chore you're behind on. It's bring-your-own-model, so mechanical sweeps can run on a small cheap model while your best one stays on the code.

And because sessions tile, the doc pass runs in one pane while feature work runs in the others. Documentation stops being the thing you'll get to after the sprint.

The free tier includes the board and the grid.

Start with the README

Don't commission a documentation project. Open a fresh session, point it at your README, and have it run every command on a clean checkout and fix what doesn't work. Twenty minutes, no strategy required, and it repairs the page more people read than anything else you've written.

Then put the weekly sweep on a schedule so you never do that twenty minutes twice.

Download SanuDesk free and give your docs their own lane, or see how the board, the grid and Loops fit together on the features page.