# Keeping API Documentation Up to Date — Routebase > Why documentation drifts away from the API, what to generate and what to write, how pinned snapshots and documentation versions work, and where a changelog comes from. Canonical page: https://routebase.dev/guides/api-documentation/keeping-api-documentation-up-to-date/ Chapter 3 of 10 · API Documentation · Last reviewed 2026-09-13 · The Routebase Team Every team with stale documentation started with correct documentation. The interesting question is not how it got wrong, it is why it was always going to. ## Documentation drifts because it is a copy Your API exists as code, and it is described as prose. Those are two representations of the same facts, kept equal by a person who remembers to edit both. That arrangement fails predictably rather than randomly. It fails during a large release, because the change is big and the deadline is close. It fails when the person who wrote the page has left. It fails on the second change to a field rather than the first, because the first one was still fresh. And it fails silently. Nothing breaks when documentation goes wrong, no test turns red, and the only signal is a consumer who built against something that is no longer true. ## Split the facts before you fix the process The way out starts by separating two kinds of content that get maintained as though they were one. **Derivable facts** already exist in the contract. Paths, methods, parameters, types, required flags, response codes, schema shapes and security requirements are all mechanically knowable, and writing them a second time in prose creates a copy with no benefit. **Authored meaning** exists nowhere else. Why the endpoint exists, what a caller is committing to, which order operations go in, what a value means in your business, and what to do when something fails are things no generator can infer. Generating the first kind is what buys the attention to keep the second kind true. Teams that write both by hand end up with a reference that is stale and concept pages that were never written. The [OpenAPI guide](/guides/openapi/what-you-derive-from-openapi/) covers what a contract can feed and where that stops. ## A snapshot beats a live feed Generating the reference raises an obvious next question, which is how current the generated output should be. Regenerating from whatever the contract says right now sounds like the strongest form of freshness, and it is the version that hurts. Your contract has work in progress in it, so a documentation portal that follows it live will publish a field nobody has released and an endpoint somebody is still arguing about. The arrangement that holds is a pin. The documentation references one released version of the contract, that reference does not move on its own, and the system tells you when a newer released version exists. Updating is then a decision somebody makes, with a diff they can read, rather than a side effect of somebody else's commit. _Figure: The contract keeps moving while the published reference stays pinned to a released version, so the documentation only changes when somebody accepts the newer one. The gap between the two stays visible rather than silent._ ## Version the documentation on its own clock Documentation versions and API versions are different lifecycles, and treating them as one causes two familiar problems. If the docs can only change when the API changes, typos and missing explanations wait for a release. If the docs change freely while consumers are still on an older contract, the page a consumer reads describes an API they are not calling. The arrangement that solves both is a documentation version with its own draft and published states, which carries a pinned reference to a contract version. You correct prose in a draft as often as you like, you publish when it is ready, and a reader on the older API can still reach the documentation that matches it. The [running several versions](/guides/api-versioning/running-multiple-api-versions/) chapter of the versioning guide covers what that costs on the API side. ## Let the diff write the changelog Once the documentation is bound to contract versions, the changelog stops being a memory exercise. Comparing the version you were pinned to with the one you are moving to produces every added endpoint, every removed field and every type change. Every new enum value comes with it, already classified as breaking or additive. That is the half people forget, and it is the half a machine never forgets. What the diff cannot see is a change of meaning behind an unchanged shape, so a tightened validation rule or a different reason for the same error still needs a sentence from a person. Generating the mechanical half is what leaves time for that sentence. ## Deprecation belongs in the docs, not only in the headers A deprecated field that is marked in the contract and not visible in the documentation is deprecated to machines only. The documentation version of a deprecation needs the same three things the API version needs, meaning what is going away, when it stops working, and what to use instead. Put it on the page for the affected endpoint rather than only in the changelog, because the reader who needs it is looking at the endpoint. The [deprecation and sunset](/guides/api-versioning/api-deprecation-and-sunset/) chapter covers the headers and the timeline. ## In Routebase A documentation version in Routebase carries pinned snapshots of published specification versions. Editing a specification afterwards does not change what your readers see, and when a newer version is published the reference shows an update banner with the version it could move to. _Screenshot: Each documentation version opens on an overview that says where it stands, what is waiting for a decision, and how much of the embedded reference actually carries a description._ Versions run through draft, review and live, with exactly one version live at a time and published versions locked so nobody edits what consumers are reading. Cloning a version to start the next one offers to pull the newest published specification versions into the clone, which keeps the snapshot update an explicit step. Changelog entries are generated from the comparison between two specification versions and edited before they go out. The [Documentation Versioning guide](https://docs.routebase.dev/doc-versioning/) covers the lifecycle, and the [Changelog guide](https://docs.routebase.dev/doc-changelog/) covers the generated entries. ## Frequently asked questions ### Why is API documentation always out of date? Because it is a copy. The API is defined in one place and described in another, so staying correct depends on somebody making the same change twice during the release where they are busiest. The structural half of that second edit can be derived from the contract, and once it is, the only writing left is the part that was never mechanical. ### Should API documentation be generated from OpenAPI? The reference should be, because every fact in it already exists in the contract and typing it a second time only creates a way for the two to disagree. The guides and the concept pages should not be, since no generator can explain why an endpoint exists or what a consumer is committing to by calling it. ### Should documentation follow the API automatically? Not without a step you control. A reference that regenerates on every contract change will happily publish an unreleased field to your consumers. The useful arrangement pins the documentation to a released version and tells you when a newer one exists. The update stays a decision, and the decision stays visible. ### How do documentation versions relate to API versions? They are separate lifecycles that reference each other. You can correct a sentence in the docs without touching the API, and you can release a patch of the API without rewriting a page. What ties them together is the reference, which is pinned to one released contract version, so a documentation version always states which API it describes. --- [Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.