In my last post, I wrote that agents won't forgive your docs. This one is about a quieter problem: keeping the docs in step with the product at all.
AI made engineers faster. A single milestone now holds dozens of pull requests, each smaller than before. When AI writes much of the code, one change often arrives as a whole series of them.
Every one of those PRs can change something a user sees, so every one might need a docs update. But most docs processes were built for a much slower stream, and they haven't changed. The weakest point is the first draft: who writes it, and who is left reviewing everything else.
For years, most teams documented features the same way. The engineer who built the feature wrote the first docs draft. The tech writer reviewed it. It made sense. The engineer knew the details: the flag names, the edge cases, the error you get when you hold it wrong. Getting those details out of a product PR on your own was slow and hard. The writer needed the engineer for the first draft.
But look at what that means at today's speed:
Writing is hard. Reviewing a stream of drafts you didn't write is hard too. Doing both for a whole milestone is how docs fall behind.
The hard part used to be the first draft, because it needed the engineer's head. With AI, it doesn't anymore. An agent can read the product PR diff, the tests and the PR description, then draft the change on the right page. That's the part engineers were crucial for, and it's now the cheapest step.
So I flipped the roles. When a product PR merges, the docs side writes the docs PR, with whatever tools speed it up. The engineer who built the feature reviews it.
Each side now does the part only they can do:
Reviewing your own feature's docs is quick. Writing them wasn't. And the writer stops reviewing a pile of strangers' drafts and starts shipping one coherent release.
A first draft is not docs. The AI draft gets the facts on the page. Making them clear, in the right place, at the right level of detail is still writing.
How the writer does that is their choice. I put what I know into a writing skill that teaches an agent how our docs are written. Its drafts land closer to what I'd write myself, and I polish less. Some days I rewrite a section by hand because that's faster. Both are fine.
What matters is that the writer decides. AI takes the part that needed the engineer's time. The craft stays with the person who cares about the reader.
Flipping the roles fixes who writes what. It doesn't yet answer the other question: how do you know which PRs in a milestone need docs, and how do you get them all done before release day? That's a topic of its own, so it gets its own post.
I'm curious how you handled it. If your engineers got faster this year, did your docs keep up? And who writes the first draft now?