How we built an Ona Automation that scans our codebase daily, detects when docs are out of sync, and opens a PR with the update already written.
In most engineering organizations, documentation lags behind the codebase. Changes ship continuously, but the docs that explain them rarely get the same attention.
Pull requests get merged, focus shifts to the next bug or sprint, and documentation quietly falls out of sync. Feature flags are added without being documented, schemas evolve without updates, and core logic changes while the docs still describe old behavior.
The issue isn't a lack of care. Once code ships, documentation becomes the lowest-priority task, and it consistently loses to more urgent work. Over time, docs are forced into a constant game of catch-up, eroding customer trust and wasting the time of every engineer who relies on them.
Tools like Mintlify help by scanning code and flagging where documentation may be out of date, but suggestions are still homework. They add another task to the backlog. We didn't want a reminder of what we missed. We wanted a pull request with the fix already written.
We built an Ona Automation that runs every 24 hours, scans our codebase for changes that affect user-facing behavior, and opens a draft PR with updated documentation that matches our tone of voice and formatting conventions. Instead of chasing outdated docs, we review automated PRs.
1. Wake up. The automation spins up in a secure, isolated environment at 8am every morning. Because we use Ona for our human development as well, the agent runs in the exact same configured environment our engineers do, with all the right tools and dependencies from day one. No time spent installing dependencies or configuring the environment.
2. Pull context. The agent clones both our code repo and docs repo into the same environment.
3. Analyze recent changes. It reads the last 24 hours of diffs, looking for semantic changes: new flags, schema updates, configuration changes, behavioral modifications. Not formatting changes or internal refactors, but changes that would make existing documentation inaccurate for a user reading it.
4. Draft the update and open a PR. The agent writes the Markdown update and opens a draft PR. Reviewing a draft takes about 30 seconds. Writing that same page from scratch would have been 30 minutes.
This is the most common question we get. You could build something similar in a GitHub Action, but the infrastructure gets messy fast. You need a persistent environment that can hold two repos in memory, manage auth tokens across different orgs, and run long context-window models without timing out.
The real advantage was our Dev Container setup. Because we already have a devcontainer.json that defines our tooling, the agent got the exact same environment our engineers use on day one. No configuration, no dependency management, no "works on my machine" debugging.
Getting the agent to produce good docs wasn't instant. A few things we learned:
Add a tone of voice guide. The agent initially sounded too robotic. We injected our docs style guide ("be concise, use active voice, use notes sparingly") into the prompt and the output quality improved immediately.
Batch changes every 24 hours. We tried running on every commit initially, but it was too noisy. A daily batch creates a single "daily digest" PR that's much easier to review than ten tiny ones throughout the day.
Teach it what not to document. The biggest challenge was getting the agent to ignore changes that users don't need to know about. We explicitly told it to skip 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. We close the bad ones and merge the good ones.
We now wake up to a notification instead of a mental note that we need to fix the docs. Our documentation stays in sync with our code without anyone scheduling time to update it.
We've received unprompted feedback from customers about how much our docs have improved. This automation is why. It runs as a scheduled Ona Automation in the background, every day, without anyone thinking about it. Engineers who previously felt guilty about letting docs drift don't have to think about it anymore.
The pattern works for any team where docs and code live in separate repos and tend to drift apart over time. If that sounds like your team, you can build this same workflow on Ona today.
This website uses cookies to enhance the user experience. Read our cookie policy for more info.