Your engineers got faster. Did your docs?

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.

The old deal: engineers write, writers review

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:

• The engineer writes docs for every small PR, next to the code, the tests and the next PR. Docs are the first thing to slip.
• The writer reviews every docs PR from every engineer, each in a different style, often without the context of the product change.
• Nobody sees the whole release. Each draft is written alone, so pages contradict each other, and a series of related PRs gets documented once per PR, each time slightly differently.

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.

Flip it: the writer drafts, the engineer reviews

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:

• The engineer checks the technical claims. Is this flag name right? Does this query really return that? Is this the error you get? That's the review only they can give, and it's the one I want.
• The writer owns every word. They know everything that went into the release, because they wrote it. They catch the contradiction between two pages, document a series of PRs once, in its final state, and keep one voice across the docs.

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.

Polish is still the writer's job

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.

Next: shipping on time

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?