An AI writer that reads pull request diffs can catch a lot. It sees renamed functions, new endpoints, removed parameters. What it can't always see is whether a code change is also a behavior change, and behavior is what the docs describe.
A function refactor that leaves the API contract unchanged probably doesn't need a doc update. A one-line change to a validator that flips a parameter from optional to required absolutely does. The diff is the same size. The doc impact is opposite. Telling them apart requires the writer to know the API contract, not just the source.
That contract lives in your OpenAPI spec.
What the spec adds
A spec-aware AI writer can:
- Reason about request and response shape. A diff that adds a field to a response is doc-relevant. A diff that adds a private helper isn't.
- Catch contract changes that look like internal changes. Tightening a validator, changing a default, renaming a query parameter often lives in code that doesn't look user-facing in a diff. The spec surfaces them.
- Connect endpoints to docs automatically. Pages built from the spec inherit changes for free. The writer only proposes updates for the narrative pages that the spec doesn't regenerate.
- Flag drift between code and spec. When the diff and the spec disagree, the writer can ask which one is right before drafting anything.
A writer with only the diff has to guess. A writer with the spec has a contract to check against.
Where ReadMe fits
ReadMe's API reference is generated from your OpenAPI spec. When you update the spec, the reference pages update with it. That covers a large class of doc changes automatically; you don't need an AI writer to rewrite an endpoint page when the spec already drives it.
What the AI Writer does on top of that is the narrative content: tutorials, getting-started guides, conceptual pages, the kind of content the spec doesn't generate. When a code change affects the spec, and the spec affects the narrative, the AI Writer drafts the narrative update.
Combined with bi-directional sync, the workflow becomes: spec changes in your repo, reference pages update on merge, AI Writer proposes the narrative updates that ride along. No copy-paste, no manual edits to pages the spec can drive.
The freshness problem
Most AI doc tools fail on freshness in a predictable way. They read the docs once at setup time, embed everything, and then drift. Three months later the model is reasoning about a version of the docs that no longer exists.
A spec-aware writer has a fresher source of truth: the spec itself, which is regenerated on every change. Pair that with versions for the docs themselves, and the writer can correctly answer "what is the current behavior?" even on a complex API with multiple supported versions in production.
What to ask when evaluating tools
Useful questions when looking at any AI doc tool that claims to handle change detection:
- Does it read the spec, or only the diff?
- How does it handle changes that affect behavior but not the public API surface?
- What happens when the diff and the spec disagree?
- Does it know which doc pages are generated from the spec and which are written by hand?
A tool that can't answer the last question will keep proposing rewrites of pages that didn't actually need a rewrite, because it doesn't realize the spec already did the work. That's a fast way to lose the team's trust.
For more on how the AI Writer reads code and proposes drafts, see Introducing GitHub AI Writer. For background on why a clean spec matters for AI-readable docs in general, see What is API Documentation.
