Convention-Based Design for Docs

One payments team got tired of the same old problem: the docs existed, but nobody trusted them. The answer wasn’t a bigger wiki. It was a rule: keep docs in a fixed folder inside each repo, tag the repo with a GitHub topic, and let a separate build turn all of that into one site.

That sounds modest, which is why it’s interesting. The docs repo doesn’t maintain its own registry, and it doesn’t need per-repo setup. Every 30 minutes, a GitHub Action checks which repos carry the topic, looks at the git tree hash for the docs folder, and rebuilds only when something has changed. Astro and Starlight do the rendering, Cloudflare serves the result, and SSO keeps the client’s version behind access control.

The old system was Confluence, and the failure mode was familiar. A search for one payment flow could turn up four pages, two of them disagreeing, one describing a service that no longer existed, and none of them saying who owned the thing. Worse, the docs could drift away from the code because the page and the pull request lived in different worlds.

The new setup tries to make drift harder. A page without a title fails the build. If a service gets renamed or deleted, the docs can be changed in the same pull request, and reviewers see the mismatch instead of discovering it months later. Ownership follows the repo, with CODEOWNERS for shared repos and git blame for the ugly details.

There’s also a clear bet on AI. Agents can read the same Markdown the site renders, straight from disk, instead of hallucinating from half a wiki and a prayer. The team says it took one engineer and one day to build the docs repo, wire up a read-only GitHub App, and ship the site. That’s the whole pitch: make the convention cheap, and people actually follow it.