Why cross-repo product docs go stale

Ask a product manager when their documentation was last accurate and you will usually get a date, not a state. That date is the last time somebody sat down, opened every repository the product lives in, and reconciled what the code does with what the spec claims.

Between those dates, the product keeps shipping.

Drift is a rate, not an event

A single repository is easy to keep honest. The spec lives next to the code, the reviewer of the pull request is also the reader of the doc, and a change that contradicts the documentation is visible in the same diff.

Now split that product across a web client, a mobile client, an API, and a jobs service — four repositories, three teams, one product. Nothing about that split is unusual, and nothing about it is wrong. But the feedback loop that kept the documentation honest only worked because everything was in one place.

Each repository now moves at its own pace. The document does not move at all. Two weeks later the gap is small enough to ignore. Two quarters later it is large enough that nobody trusts the document, and the fastest way to answer a product question becomes asking an engineer.

That is the real cost. Not the stale page — the meeting it creates. Every question that could have been answered by reading becomes a question answered by interrupting, and the interruption lands on the person with the least time to spare.

The failure is quiet, which is why it survives. No build breaks when a document stops being true. No alert fires. The only signal is a slow increase in how often someone says "let me check with the backend team", and by the time that phrase is normal, nobody remembers it used to be unnecessary.

Three reasons it keeps happening

Ownership stops at the repository boundary. Every repository has a clear owner. The behaviour that spans four of them has none. A payment flow that starts on mobile, is validated by the API, and is reconciled by a nightly job is documented three times, partially, in three places, by three people who each describe only their leg of it.

Reviewers cannot see the contradiction. A backend engineer renaming a field reviews a backend diff. The mobile copy that promised the old behaviour is not in that diff, so nothing feels wrong. Cross-repo contradictions are invisible to the only process that reliably catches problems.

Nobody reads the whole thing. Documentation is written per repository, so it is read per repository. The only reader who needs the cross-repo picture — the product manager — is also the only reader without a natural place to find it. What they get instead is four partial answers and the job of stitching them together, which is exactly the work the documentation was supposed to have already done.

There is a fourth reason that is harder to admit: updating a cross-repo document is nobody's definition of done. The pull request merges, the ticket closes, the metric moves. The paragraph that is now wrong sits in a repository the author does not have checked out.

What actually works

The fixes that survive contact with a real team have one thing in common: they do not depend on anyone remembering to update a document.

• Give cross-repo behaviour a single home. One document per user-facing capability, not one per repository. If a flow touches four services, it still gets exactly one description, and that description names all four.
• Anchor claims to code. A sentence that references a specific file, endpoint, or table can be re-checked mechanically. A sentence that describes a vibe cannot. Prefer the first kind.
• Make staleness visible. A document that shows when the code underneath it last changed is more useful than one that shows when it was last edited. The first is a signal, the second is a timestamp.
• Regenerate instead of remembering. Anything derived — endpoint lists, state machines, configuration flags — should be produced from the source, not typed out and then maintained by goodwill.

The part worth automating

None of this requires a product manager to read code. It requires the repositories to be read together, on a schedule, by something that does not get bored.

That is the assumption WeaveSpec is built on: connect the repositories that make up one product, analyse them as a single workspace, and generate the cross-repo documentation and tasks from what is actually there. The document stops being a memory of a decision and becomes a view of the system.

Drift does not go away. It just stops being invisible.