Docs That Survive Your Next Git Diff
Start with the diff, not the documentation folder
The expensive part of stale documentation is rarely the typo. It is the afternoon someone spends implementing an example that stopped working three releases ago. Adding AI can make that problem cheaper to catch, but asking a model to rewrite your entire documentation tree on every commit just creates another bill.
My starting point is git diff --name-only origin/main...HEAD. I look for changes to public interfaces, environment variables, configuration defaults, authentication, and error responses. Those are documentation triggers. An internal refactor with identical behavior usually does not need a prose rewrite.
Map public code to the pages it can invalidate
Keep a small, versioned ownership map beside the code. It can be a plain JSON file mapping source paths to documentation pages and example tests. The format matters less than having something your CI job can read without guessing.
- Map each public API module to its reference page and runnable example.
- Map configuration definitions to the setup guide and environment variable reference.
- Map command definitions to terminal examples and captured help output.
- Assign an owner who can confirm whether changed behavior requires documentation.
This map reduces both human search time and model context. If one configuration default changes, send the relevant diff and setup paragraph, not six unrelated guides.
Make examples fail before customers copy them
Move important snippets into executable fixtures, then generate their documentation copies or verify that the copies match. Run CLI examples against a temporary directory. Validate configuration samples against the same schema your application uses. Check documented response fields against contract tests.
Keep paid API calls out of ordinary pull-request checks. Use mocks for request shape, authentication headers, and response handling, then run a small, explicitly budgeted live smoke test separately. A passing mock does not prove provider compatibility, but it catches plenty of mistakes without spending tokens.
Give the model a bounded documentation job
My prompt names the changed behavior, includes the relevant diff and existing paragraph, and asks for the smallest accurate patch. It also says: identify missing evidence instead of inventing defaults, limits, or migration steps. That last instruction prevents polished misinformation from becoming tomorrow's support work.
With Fluxo, I can keep one key and one base URL, https://api.fluxorelay.com, while accessing Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok and more. It works with Claude Code, Codex, Gemini CLI and any OpenAI SDK, so the documentation task stays in the editor or terminal.
For example, I might evaluate DeepSeek V4 Flash for identifying affected paragraphs and Claude Sonnet 5.5 for reviewing a complicated migration explanation. Those are candidates, not automatic cost rankings. Measure accepted patches and total spend on your own repository before choosing a default.
Budget the retry loop and the cache
Fluxo bills per real token, including cache reads and writes, with no monthly fee. That makes a bounded workflow useful: cap input size, output length, and retries. Cache usage still belongs in the ledger; do not treat a cache hit as free or assume every repeated prompt will qualify.
Record the task, model, reported usage, actual charge, and whether the patch survived review. Cost per accepted patch is more useful than cost per request. A cheap request that produces three rounds of cleanup is not a bargain.
Ship code and documentation in the same review
Add a pull-request checkbox asking whether observable behavior changed and which documentation checks ran. Require human review for migration instructions and destructive commands. Generate drafts automatically; do not automatically publish claims about behavior you have not verified.
If you want to try this workflow, create a Fluxo account and start with one narrowly scoped documentation check. Keep any referral share separate from your savings calculation: users earn a share when people they invite pay, but that is not evidence that a documentation workflow costs less.
The target is simple: fewer broken examples, smaller review diffs, and less paid context. Documentation stays current when updating it becomes a cheap part of shipping code, rather than a cleanup project nobody budgets for.