Case studies / Establishing an AI-native product team / Documentation

Documentation that keeps up: from never done to updated every sprint

The product's documentation was in poor shape, as it is in most companies, because it is never urgent. An AI agent drafted pages three times faster until the whole product was covered. A second assistant now proposes updates from each sprint's finished work, so it stays current.

Before 1×
With the agent 3×, until the whole product was covered
Fig. 1 Documentation pages written each week, before and after the documentation agent, relative to before. Every page was still reviewed by a person.
Catching up
An Amazon Q agent, drafting pages from exported tickets
Keeping up
A sprint-end skill, reading and writing the wiki through Atlassian's Rovo MCP server
Checked by
A person, for every page and every edit
Result
Pages written 3× faster each week, until the whole product had documentation

The problem

Product documentation is never urgent. There is always a release, a customer or a defect that matters more this week, so documentation slips to the bottom of the list and stays there. Ours was in poor shape, as it is in most companies.

And documentation that isn’t maintained loses its value fast. With developers building faster using AI, the product was changing faster than anyone could write it down.

There were two problems, then: catching up, and keeping up.

Catching up: an agent that drafts pages

I built an Amazon Q agent that took exports of tickets and drafted documentation pages from their requirements. It wasn’t the ideal set-up. Working from requirements describes what was asked for, not always what was built, and better connections and more capable AI tools were still going through approval. But waiting would have cost months.

Before 1×
With the agent 3×, until the whole product was covered
Fig. 2 Documentation pages written each week, before and after the documentation agent, relative to before. Every page was still reviewed by a person.

Pages were written three times faster each week, until the whole product had documentation. A person still reviewed every page. Everything after this would build on it, so it had to be right.

Doing something urgent now, with 80% of the efficiency, is better than waiting six months for the perfect tool.

Writing the house style down

An AI asked to write documentation will write it in its own style, and differently each time. So I wrote the house style down, to sit alongside the shared rules:

  • Keep it general. No customer names; named third-party integrations are fine.
  • A fixed shape. An overview that answers the obvious questions, then the details, then configuration (split into what customers can change and what only we can), then set-up steps.
  • Written for the reader. Describe what the feature does and how it works, not how it’s coded. Professional and friendly, using industry terms without jargon.
  • Don’t repeat. Link to the page that already explains something.

With it written down, every tool that writes documentation can follow it, and the documentation reads as if one person wrote it.

Keeping up: updates from every sprint

Once the product was covered, the job was to keep it that way. The documentation updater runs at the end of each sprint as part of sign-off. It takes the feature tickets each product owner finished, compares their changes with the current documentation, and proposes edits.

  1. 1 Finished work The owner's tickets closed this sprint
  2. 2 Compare What changed, against the current documentation and the house style
  3. 3 Propose Small edits where things changed; other ideas listed separately
  4. 4 Approve The owner accepts, edits or rejects each one in the chat
Fig. 3 Keeping up. At the end of each sprint, each product owner runs the updater for their own finished tickets. It proposes edits to the pages those tickets touched; nothing changes until the owner agrees.

The hard part was stopping it doing too much. AI doesn’t give the same answer twice, so left alone it suggests a fresh rewrite of the page every time a ticket touches it. That is the opposite of saving time. The product owner may have written a page a certain way for a good reason, and shouldn’t have to defend it every sprint.

So the updater’s job is narrow: change what the sprint changed. Anything else it would add is listed separately at the bottom, as a suggestion the owner can take or leave.

Each product owner runs it for their own tickets. They know what changed and why, so they can tell a good edit from a plausible one, and no update is missed because someone forgot.

What wasn’t finished

The updater had had the least work of all the tools when I moved on. The core was in place and it worked, but it still needed tuning to stop it reaching for the same page again and again. Like the other tools, it also read the shared pages live every time it ran, which was slower and more expensive than it needed to be.

If I built it again

What it reads

What I did thenTicket exports, handed to Amazon Q, so pages described what had been asked for.

What I'd do nowThe tickets and the code changes that closed them, through connectors, so pages describe what was actually built.

How it edits

What I did thenSuggestions in the chat, which drifted towards rewriting the whole page.

What I'd do nowEdits limited to the sections a ticket touched, shown as before and after for each paragraph. Anything else is an optional extra.

What it remembers

What I did thenNothing stopped a rejected suggestion coming back next sprint.

What I'd do nowRejected suggestions are recorded against the page, so the owner explains a choice once.

When it runs

What I did thenStarted by each product owner at the end of the sprint.

What I'd do nowDrafts prepared automatically when a ticket closes and left for the owner to approve. The conversation is still there for the hard ones.

How it's tested

What I did thenJudged on each sprint's output as it came, with no fixed test.

What I'd do nowA set of past tickets with the right documentation change agreed in advance, rerun after every change to the instructions.

Fig. 4 If I built the documentation tools again. Left: what I did in 2026 with the tools approved at the time. Right: what I'd do today.

Two rows matter most. Reading the code as well as the ticket would close the gap between what was asked for and what shipped, which is where documentation usually goes wrong. And remembering rejected suggestions is what makes a tool like this pleasant to live with rather than something people quietly stop running.

What carries into your business

Every business has a document nobody keeps up to date: the staff handbook, the price list, the process someone wrote three years ago. The same approach works.

  1. Catch up first, with whatever works now. A reviewed draft beats a blank page.
  2. Write the house style down so every draft sounds like you.
  3. Update from what changed, not from scratch, so people only review the difference.
  4. Have the person who made the change approve it.

Got paperwork that follows a pattern?

An hour's chat costs nothing. We'll find where the quick wins are in your business.

Talk to us →