Stale documentation is a structural problem. If the docs are a separate artifact that a human has to remember to update, they will drift, and no amount of process discipline changes that for long.
Generate everything generatable. Reference documentation should come from the OpenAPI. Examples should come from the schema examples in the contract. SDK snippets should be generated. The moment the contract changes, the reference changes, with nobody in the loop.
Keep the hand-written parts — the guides, the concepts, the tutorials — in the same repository as the code and the contract, so a pull request that changes behavior can be reviewed alongside the prose that describes it. Documentation in a separate CMS that only the docs team can edit is documentation that will lag every release.
Test the examples. If your getting-started guide contains a curl command, run it in CI against a real environment. Broken examples in a getting-started guide do more damage than missing ones, because they destroy confidence at the exact moment you are asking for it.
And use Overlays for the parts that need to differ per audience rather than maintaining forked documents. One contract, layered derivations, no divergence.
