# 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.

{% callout type="tip" title="This page is the demo" %}
There is no slide deck. The thing being proposed is the thing rendering this
sentence. Try the **Copy for LLM** button at the top of this page — you will
get clean Markdown, not scraped HTML, because Markdown is what this page
actually is.
{% /callout %}

## 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.

{% step n=1 title="Publishing 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.
{% /step %}

{% step n=2 title="Noticing 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](how-docs-are-generated.md), 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.
{% /step %}

## 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](measurements.md).

{% callout type="note" title="For comparison" %}
Cloudflare publish the same measurement for their own docs and report roughly
7×. They built a network-layer converter to reconstruct Markdown from HTML at
the edge. Our source is already Markdown, so we skip that component entirely —
serving it is a file copy.
{% /callout %}

## What we built

Two halves, and they are useless apart.

{% step n=1 title="The 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](ai-consumability.md).
{% /step %}

{% step n=2 title="The 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.

1. **A release goes out** in any SEON repository that has public documentation.
2. **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.
3. **Its OpenAPI spec is regenerated** as part of the same release, so the
   machine-readable surface never lags the release that changed it.
4. **The customer-impacting part of the release notes is extracted**, and an
   agent writes the corresponding change into this documentation repository.
5. **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.
6. **The branch builds a preview**, so the rendered page is read before anyone
   outside sees it.
7. **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.
{% /step %}

## 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.

{% callout type="note" title="An editor is optional, not a prerequisite" %}
If we later decide a visual editor is worth building, it writes Markdown into
the same repository and nothing else changes. That is the difference between a
content model and a CMS: we can add the editing surface whenever it earns its
place, instead of accepting one up front and building everything around it.
{% /callout %}

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.

{% callout type="important" title="Two axes, not one" %}
The configuration layer decides what is **public versus internal**. It also
decides what is **current versus superseded** — a legacy page can stay
published for people who bookmarked it while dropping out of every agent index,
so nobody's coding assistant learns a path we no longer recommend.
{% /callout %}

## 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

1. **Finish the corpus.** The IDV knowledge base is here; the rest of
   `docs.seon.io` is not.
2. **Wire the pipeline to a real repository** and let it open its first pull
   request against this site.
3. **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.*