Why this site exists

SEON's public documentation is written by hand, published through a CMS, and updated whenever somebody remembers. The product it describes changes every day. The gap between the two is invisible until a customer hits it.

This site closes it. Documentation lives as Markdown in git, so a correction takes minutes rather than an afternoon and the pages are cheap enough for an AI agent to read — which matters more every month, because an LLM now reads our documentation before any engineer does.

The goal is documentation that cannot go stale, rather than documentation somebody remembers to update. It is also the pitch for itself, which is the point: every claim below can be checked against the page you are reading.

Documentation that cannot fall behind

Documentation goes out of date because keeping it current is somebody's discretionary work, and discretionary work loses to whatever is urgent that week. Removing that dependency is what the project is for.

Two things stand between a change in the product and a change in the docs. One of them is already gone.

1Publishing now costs almost nothing — this is built

The first cause of staleness is friction. When updating a page means a CMS queue and somebody's afternoon, small corrections never happen and the rot is gradual.

Here a change is a pull request: someone reads the diff, approves, and it is live within a minute of merging. Fixing a wrong sentence is cheap enough to do on the way past, which is the only way small corrections ever get made.

2Noticing what changed — this is the proposal

What remains is detection. Somebody still has to realise that a merge changed something a customer can observe. That is the pipeline described in How this documentation is generated, and it does not exist yet.

Build it and the loop closes: the product ships, the pipeline notices, a human approves, and the docs are never more than one release behind. Until then the claim is narrower — keeping a page current is now cheap enough that there is no excuse left, but somebody still has to decide to do it.

The second problem: what a page costs to read

Staleness is not the only way documentation fails a developer. Increasingly it is not even read by one first — when somebody integrates SEON, an LLM reads our docs and writes the integration from what it found. So "how expensive is this page to read" stopped being an academic question. A stale page and an unaffordable one fail the same developer in the same way.

One knowledge-base page on docs.seon.io costs an agent about 141,000 tokens — enough that a model with a 200,000-token working memory can hold two of our pages and nothing else. The same pages here cost a few thousand each.

Measured on four pages that exist on both sites, this one is between 13× and 96× cheaper to read, and carries more content rather than less. The page-by-page figures, the method, a capability-by-capability comparison of both sites and the gaps on both sides are on Measurements.

What we built

Two halves, and they are useless apart.

1The platform — Markdown in git, rendered with Markdoc

Every page on this site is a Markdown file in a repository. Markdoc — the framework Stripe built for docs.stripe.com and released under MIT — turns it into the page you are reading, with custom tags for callouts, steps and API reference blocks generated from OpenAPI specs.

Three things fall out of that choice for free:

Versioning. Git history is the version record, for the API reference, SDK guides and knowledge base alike.
Editing. Anyone who can write Markdown can fix a page and open a pull request. No CMS queue.
Agents. Raw Markdown at a predictable URL, llms.txt indexes, and a Copy for LLM control. See Reading these docs as an agent.

2The pipeline — documentation as a build output

The trigger is a release, not every merge. A release is already the moment a team has decided something is worth shipping, and several teams here already mark which of theirs are external.

A release goes out in any SEON repository that has public documentation.
That repository says how its own domain is documented. A file alongside the code describes the conventions for this product and what may or may not be exposed — so the rules live with the thing they describe rather than in one central policy that nobody outside the docs team ever reads.
Its OpenAPI spec is regenerated as part of the same release, so the machine-readable surface never lags the release that changed it.
The customer-impacting part of the release notes is extracted, and an agent writes the corresponding change into this documentation repository.
A pull request is opened here — against the docs, not against the service, so the reviewer is looking at prose rather than at a diff of someone's code.
The branch builds a preview, so the rendered page is read before anyone outside sees it.
Merge, and a GitHub Action publishes. Live within about a minute.

Step 7 already works — it is how this page reached you. Steps 1 to 6 are the proposal, and step 6 is a small addition rather than a hard one: the build runs on every push today, it simply is not wired to pull requests yet.

The rule that governs all of it: the pipeline opens a pull request, never publishes. The machine proposes; a person disposes.

What this changes about shipping docs

Choosing Markdown in git is not only a format decision. It hands documentation the entire workflow that code already has, and none of it has to be built.

Every change is a pull request. Someone reads the diff before it ships, and anyone can build the whole site locally to see the rendered page first. Wiring that build to pull requests as a per-branch preview is a small addition we have not made yet — but branch isolation, review before merge, and a production that only moves when someone merges are all there by default rather than by configuration.

Version history is free and complete. Who changed a page, when, why, the diff between any two points in time, and a one-command revert — across the API reference, the SDK guides and the knowledge base alike. That is also a cleaner audit trail than a CMS revision log for the pages that regulated customers treat as contractual.

Anyone with repository access can write. This used to be the strongest argument for a CMS: a non-engineer could publish, and a git repository shut them out. AI coding assistants have largely collapsed that barrier — editing a Markdown file and opening a pull request is now something anyone can do by describing the change they want.

The honest caveat is that this is still a change to how people work, and docs-as-code migrations fail on author workflow far more often than on tooling. The barrier is much lower than it was two years ago. It is not zero.

Why the filter matters more than the generator

Most merges change nothing a customer can see. A pipeline that opens a pull request on every merge gets muted inside a week, and muted pipelines do not come back.

So the component that decides whether to speak is worth more than the one that writes the prose.

The other half of that judgment is what may be said, and it differs by repository. This is not a rule anyone would have to invent — it already exists in code. id-verification-service generates two OpenAPI specs from the same annotations, one internal and one external, and the vendors SEON integrates for document and biometric checks appear 59 times across the internal spec and not once in the external one. Another team's repository will draw that line somewhere else entirely.

So the configuration layer is per repository, and its job is to inherit rules the code already encodes rather than impose one global policy on every team.

What is real, and what is not

Being straight about the seams is what makes the rest credible.


Working now	This site. The Markdoc render, the agent surface — Markdown twins, three tiers of `llms.txt`, `robots.txt` — the API reference generated from the services' own annotated source, and the IDV knowledge base exported from the live docs.
The actual work	Nothing generates knowledge-base prose today. Detecting what changed and drafting it is the new part, and exactly where human review stays mandatory.
Not attempted	Cutover. This site stands in parallel to `docs.seon.io` — no redirects, no SEO migration, no DNS. That is the follow-on project this demo exists to justify.

What it would take next

Finish the corpus. The IDV knowledge base is here; the rest of docs.seon.io is not.
Wire the pipeline to a real repository and let it open its first pull request against this site.
Decide who owns docs. This changes the publishing workflow, and docs-as-code migrations fail on author workflow rather than on tooling.

Everything on this page is a Markdown file in the same repository as the rest of the site. If you disagree with a number, the source is one click away in the footer.