Keeping documentation in sync with a codebase that ships weekly

The gap opens one merge at a time

Nobody decides to let documentation go stale. It happens through a sequence of individually reasonable choices, each one made under deadline, none of them worth blocking a release over.

A parameter gets renamed. A default changes. An endpoint gains an optional field. A flag is deprecated but still accepted, so nothing breaks. Every one of these is a five-minute documentation update that loses to a shipping deadline, and every one of them is invisible the moment it's skipped — the build is green, the tests pass, and the page describing the old behaviour sits there looking exactly as authoritative as it did last week.

By the time anyone notices, the question isn't which page to fix. It's which pages can still be trusted, and that question doesn't have a cheap answer.

Why the usual fixes decay

Most teams reading this have already tried at least two of the following:

• A docs checkbox in the pull request template. Ticked honestly for a few weeks, then ticked reflexively, then ticked by a bot.
• A quarterly documentation sprint. Clears the backlog, then the backlog refills on the same slope it did before.
• A rotating documentation owner. Converts a distributed problem into one person's unfalsifiable second job.
• A style guide. Improves the docs that get written. Has no opinion about the ones that don't.

These decay for a structural reason, not a cultural one. Code and documentation have different failure modes. Wrong code fails loudly — a test breaks, an alert fires, someone opens an incident. Wrong documentation fails silently. No system notices, and the only feedback arrives weeks later as a support ticket that nobody traces back to a page.

Any fix that depends on a person remembering to update a second artifact, at the exact moment they're trying to ship a first one, is asking discipline to compensate for that asymmetry. Discipline loses on a long enough timeline — not because engineers are careless, but because the incentive gradient runs the other way every single time.

How to tell how bad yours is

Drift is hard to argue about because everyone estimates it differently and nobody has a number. Three checks give you one in an afternoon, without instrumenting anything:

• Run the quickstart on a clean machine. Follow your own getting-started page exactly as written, changing nothing, on an environment with no prior setup. Count the places you have to deviate. This is the single most predictive check, because the quickstart is the page with the widest readership and the least frequent maintenance.
• Pick five things that changed last quarter — a renamed flag, a new endpoint, a changed default, a deprecated option, a new configuration key — and search the docs for each. What you're measuring isn't whether the docs are wrong; it's the lag between a change shipping and a page reflecting it.
• Ask support which pages they've stopped linking. Support teams route around bad documentation quietly and early. They usually maintain an informal list of pages they'd rather explain themselves than send someone to, and that list is the most accurate drift audit in the company.

If those three turn up more than you expected, the useful conclusion isn't that the team was careless. It's that the pages nobody flagged are the ones with no mechanism behind them.

How Git2Docs closes it

The approach is to remove the step where drift enters, rather than adding a step to catch it.

Documentation is generated from the repository

Git2Docs parses your source with tree-sitter across TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, and Ruby, then synthesises documentation from what's actually in the code. Signatures, parameters, endpoints, and configuration options come from the thing they describe, so they can't disagree with it.

It resyncs on every push

A merge to a connected branch triggers regeneration. There's no scheduled job, no publish button, and no window during which the published docs describe a version you no longer ship.

Documented examples are executed, not just written

This is the part most tooling skips. A generated CLI command or API call is exercised against your live deployment by a coding agent, and mismatches between documented and observed behaviour are reported and batched into a fix. An example that no longer works becomes a failure with a trace, rather than a quiet inaccuracy that erodes trust in every page around it.

Coverage is measured

The repository dashboard reports which parts of your public surface have documentation and which don't — the same way test coverage reports tested code. You can't manage drift you can't see.

What this looks like in practice

A typical week on a connected repository:

1. An engineer merges a PR that renames a configuration key and adds two optional parameters to an endpoint. They write no documentation.
2. Git2Docs picks up the push and reparses the changed surface.
3. The affected pages regenerate. The old key disappears, the new one is documented with its type and default, and the endpoint reference gains the two parameters.
4. The validator runs the documented examples against the live deployment. One quickstart snippet still passes the old key name; it's flagged and corrected.
5. The published site updates, and the support chatbot that answers from it is now answering from the current version — not last quarter's.

The engineer did not open a documentation file, and the docs did not fall behind. That's the whole mechanism: not better habits, but one fewer place for habits to matter.

When this isn't the right fit