# How this differs from Backstage

The question comes up because both approaches start the same way: Markdown files
living beside the code, rendered somewhere else. That is where the resemblance
stops.

{% callout type="note" title="The short answer" %}
They solve different problems. Backstage is an **internal developer portal**, and
TechDocs within it is a docs-like-code plugin for engineers. Continuous Docs is a
**customer-facing documentation site** plus a pipeline that drafts updates from
releases. This is not a Backstage alternative and should not be positioned as one.
{% /callout %}

## What each one is

| | Backstage TechDocs | Continuous Docs |
|---|---|---|
| Audience | Engineers inside the company | Customers, and the agents integrating for them |
| Sits inside | The Backstage developer portal | Its own published site |
| Renders with | MkDocs | Markdoc |
| Source of a page | Written by the owning engineer | Written by a person, or drafted from a release |
| Question it answers | "Where are the docs for this service?" | "Is what we published still true, and can a machine read it?" |

Spotify describe TechDocs as their
*"homegrown docs-like-code solution built directly into Backstage"* —
documentation discovered from a service's page in the software catalogue. It is built for internal technical documentation, and it is
good at that.

## Where this is different

**The internal/external question is the whole point here.** Backstage does not
ask it, because everything in a developer portal is internal by definition. For a
customer-facing site it is the first question, and it already has an answer in
our code: `id-verification-service` generates separate internal and external API
specs from the same annotated source, and the vendors behind its document and
biometric checks appear 59 times in one and never in the other. The
per-repository disclosure file extends that same rule to prose.

**Staleness is treated as the adversary.** Moving documentation next to the code
does not stop it going out of date — a TechDocs page rots exactly as a CMS page
does, just in a different location. What changes that is a pipeline watching
releases and proposing the update. That is the part worth defending, and the part
Backstage has no equivalent of.

**The agent surface has no counterpart there.** Raw Markdown at predictable URLs,
`llms.txt` indexes, deprecation that removes a page from agent ingestion while
leaving it readable — see [Reading these docs as an agent](ai-consumability.md).
An internal portal has little reason to build any of that.

## Where Backstage is stronger

Being straight about this is the difference between a comparison and a sales
pitch.

**Discovery.** Which repositories have documentation, who owns it, whether it is
healthy — the software catalogue answers that across an entire organisation.
Nothing here does, and nothing here is trying to.

**Maturity.** Years in production at many companies, a substantial plugin
ecosystem, and search across everything. This is a hackathon project with 27
pages.

**Internal knowledge.** Runbooks, architecture decision records, on-call
procedure — that material belongs in a developer portal and emphatically not on a
public documentation site. If SEON wants a home for it, Backstage is a reasonable
answer and this is not.

## The closer analogy

Not Backstage. The nearest comparison is Stripe's documentation pipeline, or a
hosted platform such as Mintlify with a generation step placed in front of it.

## They compose rather than compete

If SEON adopts Backstage later, the two fit together rather than colliding. The
same per-repository file that tells this pipeline how a domain is documented
could carry the TechDocs annotation as well, and the documentation repository
becomes another entity in the catalogue. Internal documentation goes to the
portal; customer-facing documentation goes through the pipeline to the public
site.

The thing to defend in that conversation is the **relevance filter** — deciding
whether a release changed anything a customer can observe, and what may be said
about it. That is what neither a developer portal nor a hosted docs platform
provides, and it is the part of this project that is genuinely ours.