Your docs live in five formats. Generate one site from the source instead.
Every project I work on has the same documentation mess. The REST API is described in an OpenAPI file. The MCP server lists its tools in its own schema. The C++ library carries Doxygen comments. The Go helper has godoc. The Rust crate has rustdoc. The guides are Markdown files in a docs folder that nobody has opened since spring.
Each of those is the source of truth for one slice of the project. The website that is supposed to explain the whole thing is a sixth copy, written by hand, and it starts lying the week after it ships. A parameter gets renamed in the spec and the site keeps the old name. A tool is removed from the MCP server and the guide still teaches it. Readers cannot tell which copy to trust, so they trust none of them and go and read the code instead.
The fix I have settled on is boring: stop maintaining the sixth copy. Generate the site from the sources you already have.
What a source-first generator actually does
The tool I use for this is Sourcey, an open source documentation generator, currently at version 3.9.5 under AGPL-3.0. It reads OpenAPI, MCP, Doxygen, godoc, rustdoc and Markdown, and builds one static site from all of them. You can install it with npm, Homebrew, Docker or Nix, so it drops into a normal build pipeline without ceremony.
Two properties matter more to me than the feature list.
First, the inputs are artifacts the project already maintains for other reasons. The OpenAPI file is what client libraries generate from. The doc comments are what maintainers read inside their editors. When the site is built from those files, a documentation fix becomes a code fix, reviewed in the same pull request as the change it describes. The site cannot drift away from the spec, because the spec is an input to the site.
Second, the output is a static site you own. There is no hosted docs platform in the middle, no per-seat pricing, and no export dance when you want to leave. You can host the output anywhere that serves files, keep one build per release, and rebuild the docs for an old version from its tag when a user who is still on it comes asking questions.
Why this matters more than it used to
A growing share of documentation readers are not people. Agents read your OpenAPI file and your MCP tool list directly, and they act on what those files say. People read the website. When the schema and the site disagree, the agent and the human end up working from two different sets of facts, and the bug report that follows is miserable to reproduce because each side swears the docs said something else.
One generated site removes that split. The human page and the machine-readable source describe the same build, from the same inputs, at the same commit. If a fact is wrong, it is wrong in exactly one place, and fixing it there fixes it everywhere.
The part I did not expect
The generator is published by the same project behind Sourcey, which also maintains two public registries I already use: a startup credits registry kept as canonical YAML, one file per company, and a set of agent readiness report cards that grade whether software can use a service without a person in the loop. In the current signed release, the credits registry holds 607 companies and 669 offers, and every record carries the source it came from and the date it was read. Underneath both sits a provenance engine whose whole job is to give published facts a history that anyone can verify from the files alone.
That habit is the real reason the docs tool works the way it does. The registries and the generator share one rule: a published fact should point back at its source, and the published output should be something a stranger can re-derive. Applied to documentation, that rule is the difference between a site you maintain and a site you can trust.
My working rules for docs now
- If a fact already exists in a schema or in code comments, it gets generated into the site. It is never retyped by hand.
- If a guide needs real prose, the prose lives in Markdown next to the code and is pulled in at build time.
- If the site cannot be rebuilt from a clean checkout, it is not documentation yet. It is a screenshot of documentation.
None of this writes the hard parts for you. The examples, the ordering, the judgement about what a new reader needs first: that is still human work. What generation removes is the copying, and the copying was where the lies crept in.
Facts about the tool and the registries were read from Sourcey open source and the current signed registry release sha256:867e60b6… (policy as of 2026-11-17) on 2026-11-17.
Top comments (1)
Generating the site from specs and language doc comments removes a lot of drift, but prose guides can still depend on the exact version they accompany. I'd build from tagged releases and publish a version selector, then run a clean-checkout build for the current tag and one older tag in CI. That makes the promised historical rebuild practical when someone is still using an older client.