# Pitch deck

The hackathon pitch, in the medium it is arguing for. Everything below is a
slide; the deck itself is the same content in a room.

## Our docs can't keep up with our product

**Today.** Written by hand, published through a slow CMS, updated whenever
somebody remembers — while the product it describes changes every day. Agents
read stale pages and integrate SEON wrong.

**Where we want to be.** Every page plain Markdown, held in git. Updates
generated from what actually shipped. Reviewed and published in minutes rather
than weeks. Readable by the agents doing the integrating.

## So we rebuilt it

SEON's documentation as Markdown in git — live, on real content, at
[hackathon.seondf.net](https://hackathon.seondf.net). The site you are reading
is the thing being pitched.

## Why Markdown-based docs

The format decides who — and what — can actually read our documentation.

**Readable by agents.** LLMs and coding agents read our docs before any engineer
does. Every page is served as raw Markdown at a predictable URL, with `llms.txt`
indexes for discovery.

**Faster to edit.** Anyone who can write Markdown can fix a page and open a pull
request. No CMS queue, no publish cycle to wait on.

**Versioned by default.** Every page lives in git — full history, diffs and
rollback across API reference, SDK guides and knowledge base alike.

## What our docs cost an agent today

Measured across four live `docs.seon.io` pages:

| | |
|---|---|
| **24×** | Fewer tokens to read the same page as Markdown instead of as served HTML |
| **141k** | Tokens an agent burns fetching a single knowledge-base page today |
| **49%** | Of that page is a JSON copy of content the agent already has |

The page-by-page figures and the method are on [Measurements](measurements.md).

## What we serve to agents

Built and merged — 4,551 tokens for the page that costs 60,281 today.

**Markdown at two URLs.** Every page published as raw Markdown at both
`/page.md` and `/page/index.md`, with content negotiation on an `Accept` header
for agents holding the canonical link.

**llms.txt, three tiers.** A root index of every page, a per-section index for
pulling one product without the rest, and `llms-full.txt` carrying the whole
corpus for bulk ingestion.

**Current, not just public.** Deprecated pages still render and still resolve,
but drop out of every index and crawl — so an agent is never led to a path we no
longer recommend.

Full detail in [Reading these docs as an agent](ai-consumability.md).

## Stripe already solved this

Markdoc powers `docs.stripe.com`, and they open-sourced it.

**Proven at scale.** Stripe built Markdoc for what they call their largest and
most complex content site, then adopted it company-wide — thousands of pages,
hundreds of thousands of lines of Markdoc.

**Free to run.** MIT licensed and open source. No per-seat or per-project licence
fee, which is exactly what the commercial documentation platforms charge for.

**A benchmark we already use.** `docs.stripe.com` is the internal reference for
what good documentation looks like. Adopting the framework behind it makes that
target concrete rather than aspirational.

## We control the whole stack

No CMS in the critical path, and no vendor deciding what our documentation is
allowed to do.

- **Fast by default** — static Markdown, no CMS round-trip on every page load
- **No lock-in** — MIT licence, and the content is plain files we own outright
- **Built to fit** — custom tags for exactly the components our docs need

## Docs get the workflow code already has

None of this has to be built — it is what git and pull requests already do.

**Reviewed before it ships.** Every change is a pull request: someone reads the
diff, and the whole site builds locally to check the rendered page. Production
only moves when a person merges.

**History and rollback.** Who changed a page, when and why; the diff between any
two points; a one-command revert. A cleaner audit trail than a CMS revision log.

**Anyone can write.** The CMS existed so non-engineers could publish. AI coding
assistants have largely removed that barrier — a visual editor becomes optional
rather than a prerequisite.

## Docs become a build output

Every docs page in Markdown — proved on IDV first.

**A — the platform.** Export `docs.seon.io` content out of Strapi into Markdown;
API reference, SDK guides and knowledge base alike; rendered with Markdoc, held
in git so versioning is free; raw Markdown at predictable URLs for agents.

**B — the pipeline.** Triggered on release; filters for anything a customer can
observe; applies each repo's rules for what is public and what is current; opens
a pull request — it proposes, never publishes.

[How this documentation is generated](how-docs-are-generated.md) walks a release
through it end to end.

## The more we publish, the better SEON integrates

Documentation coverage is quietly becoming an integration-quality metric.

- **More content** — automation makes detail cheap to produce and cheap to keep current
- **Better agent grounding** — agents integrating SEON read complete, current pages
- **Fewer wrong integrations** — support load and SE time fall as the docs stop lagging

## The pitch, presented

{% video src="https://www.youtube.com/watch?v=Xxzqd2XgcFQ" title="Continuous Docs — hackathon pitch" /%}