Documentation drifts. Every release changes function signatures, response shapes, or CLI flags, and the docs lag behind because engineers do not enjoy updating them. A terminal AI agent can help documentation teams find those gaps before they become user complaints.
We tested OpenCode on a docs update task: a TypeScript SDK had changed its authentication flow, and the guide needed new code examples. The agent read the source, read the existing doc, and produced a marked-up diff showing what to update.
The Doc Sync Workflow
The useful workflow is comparison, not generation. You point OpenCode at:
- The doc file you want to update
- The source files that implement the feature
- A short description of what changed in the release
Then ask: "What in this doc is now outdated compared to the source?" The agent returns a list of mismatches, often with proposed replacements. You review, edit for tone, and commit.
Give the agent the release notes or changelog entry first. It uses that context to know which parts of the source changed and which doc sections are most likely affected.
What It Handles Well
Three tasks produced good results:
- API reference updates. The agent compared function signatures in the source to the parameter tables in the docs and flagged renamed or removed fields.
- Code example refresh. It generated new examples that matched the current SDK, including imports and error handling.
-
CLI flag updates. For a command-line tool, it read the parser definition and updated the
--helpdocumentation and usage examples.
The output still needed a human editor for tone, structure, and edge-case notes. But the agent did the part documentation teams dislike most: finding every place the code had changed.
Limits and Risks
The agent cannot judge whether a doc change is user-facing or internal-only. It will flag every signature change, including ones that do not matter to readers. You still need to decide what belongs in the docs.
It also struggles with narrative docs. A conceptual explanation of why a feature works a certain way is outside its scope. The agent is a fact-checker for reference docs, not a storyteller for guides.
Always run the generated code examples before publishing them. The agent can produce syntactically valid examples that no longer compile because of an import change or a dependency bump it did not know about.
When to Add It to the Docs Process
Documentation teams that maintain API references, SDK guides, or CLI manuals will get the most value. If your docs are mostly conceptual, the benefit is smaller. The sweet spot is a team that ships frequent releases and spends hours each sprint checking that examples still work.
Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.
Top comments (0)