I stopped writing docs, and let agents do it instead

TL;DR: I built an autonomous agent on Ona that doesn't just suggest changes, but actually writes the Markdown and opens a draft PR for me. We now no longer chase outdated docs and merely review automated PRs. Here is how it works.

There is a tweet from Lenny Rachitsky going around right now that really hit home for me. He asked engineers what AI tools they desperately wish existed.

High on the list? Tools to help with documentation.

I felt this in my soul. We have all been there. You finally get that green checkmark on the pull request and merge it. And then, that sinking feeling hits. You forgot the docs! But tomorrow brings a new bug, a new sprint, or a new fire.

The result is that documentation is always playing catch-up with the code. It’s a constant, losing race to keep the docs as true as the software itself.

The spark: suggestions vs. action

A few weeks ago, I saw Mintlify launch agent suggestions. If you haven't seen it, an agent scans your code and suggests places where your docs might be out of date. It was a lightbulb moment for me, as I loved the proactive approach.

But as I used it I realized it wasn't bringing the entire solution I was dreaming of. Mintlify’s agent acts more like an observant, project manager that taps you on the shoulder to say 'Hey, Siddhant, you forgot to update this parameter in the docs.'

That is helpful, but it’s still a kind of 'homework'. It’s another task on my Linear board. I didn't want a manager telling me what I missed, I wanted a teammate to help me do the work. In short: I didn't want a 'suggestion', I wanted a pull request.

An experiment with agents

Then it clicked. In November, we launched Ona Automations as a way to run background agents in secure sandboxes on a schedule. I realized I could use this as a perfect way to have an agent actually do the docs writing work for me.

So, I built a 'docs sync agent'.

The concept is simple: an autonomous script that runs on a schedule (every 24 hours), scans our codebase for changes, finds something noteworthy, writes the documentation and opens a pull request.

Here is the flow, as you can see in the diagram below:

1. Wake up: The agent spins up in a cloud sandbox at 8 AM.
2. Context: It clones both our code repo and docs repo.
3. Analysis: It reads the last 24 hours of diffs, looking for semantic changes (new flags, schema updates).
4. Action: It drafts the Markdown update and opens a PR.

You might ask: Why not just run this script on your laptop? A 'self-healing' repo needs to run even when I’m on vacation. It needs to run at consistent intervals, regardless of whether my laptop lid is closed or if I’m on a different branch. So it needs to be infrastructure, and not a local inconsistent hack.

Why not GitHub Actions?

This is the most common question I get: 'Couldn't I just build this in a GitHub Action?'.

You could, but the infrastructure gets messy fast. You need a persistent environment that can hold two massive repos in memory, manage the auth tokens to write to different orgs, and run long context-window models without timing out. But the real secret sauce was our Dev Container setup.

Because we already use Ona for our human development, we have a devcontainer.json that defines exactly what tools we need (Node, Go, Git configurations, linters). When I spun up this agent automation, I didn't have to spend days installing dependencies or configuring the environment. I just pointed the agent at our existing definition. Which meant my agent had the exact same configured environment that I do, on day one.

The learnings: tuning the intern

Now, instead of waking up to a mental note that I need to fix the docs, I wake up to a notification.

This is a massive win. Reviewing a draft now takes me 30 seconds, whereas writing that page from scratch would have been more like 30 minutes.

But getting the agent working this well wasn't instant. We’ve been tuning this agent for some time, here is what we learned:

• Add a tone of voice guide: At first, the agent sounded too robotic. We had to inject our 'docs style guide' to 'be concise, use active voice', etc.
• Batch changes every 24 hours: We initially tried running this on every commit, but it was too noisy. We realized that batching changes every 24 hours created a nice 'daily digest' PR that was easier to review than 10 tiny ones.
• Ignore noisy directories: The biggest challenge was teaching it what not to document. We had to explicitly tell it to ignore test/ directories, dependency bumps, and internal refactors. Without that, it tries to document everything.

It still has 'junior engineer' moments, sometimes getting excited about a change that users shouldn't see, but because it opens a draft PR, the risk is minimal and we just close the bad ones and merge the good ones.

If you hate writing docs as much as I do, and as much as the engineers in Lenny’s thread do, you can build this same workflow on Ona today.

Discover Ona Automations →