SaaS

Developer experience.
Answers from the API.

Developer support has an unusual property: the correct answer is almost always derivable from artefacts you already own — the OpenAPI spec, the SDK source, the changelog. A system that answers from prose documentation is working from a lossy copy.

GROUND IT IN THE SPEC

Most documentation assistants index the docs site. That inherits every problem the docs have: pages describing a deprecated parameter, an example that stopped working two releases ago, a guide written against the previous major version. The assistant then reproduces those errors confidently, and a developer wastes an hour before discovering the documentation was wrong rather than their code.

The alternative is to ground the system in machine-readable sources of truth: the API specification, the SDK source, the type definitions, the changelog, the migration guides. Those are generated from or checked against the running system, so they are correct by construction in a way prose is not.

Prose documentation still matters — it carries intent and idiom that a spec cannot. But it is a secondary source, and where the two disagree the spec wins and the system should say so. That single ordering removes most of the ways a developer assistant misleads people.

WHAT IT SHOULD DO

Generate working examples

In the caller's language, against the current spec, with their actual parameters. Better still, validate the generated call against the spec before returning it — a syntactically checked example is worth several prose paragraphs.

Diagnose an error response

A developer pastes a status code and payload; the system explains what triggers it in your API specifically and what to change. This is often the highest-value single interaction in developer support.

Version-aware answers

Answering for the version the developer is on, not the latest. Most developer frustration with documentation is a version mismatch, and this is one of the few places a retrieval system can fix it cleanly.

Surface the documentation gaps

Every question the system answers badly is a documentation defect with a log entry. Feeding that back is often worth more than the assistant itself, because it improves the source everyone else reads too.

THE INDEXING DISCIPLINE

Reindex on release, automatically, as part of the pipeline. An assistant that lags the API by a sprint is generating wrong answers on purpose, and the lag is invisible to users until they are already confused.

Chunk code and specs structurally rather than by character count. An endpoint definition split in half mid-schema retrieves badly and reads worse. This is one of the largest quality levers in a developer-docs retrieval system and it is a parsing decision rather than a model one.

And measure with real questions from your support channels, not invented ones. The distribution of what developers actually ask is quite different from what a docs team expects, and it is sitting in your ticket history waiting to become an evaluation set.

GROUNDED IN THE SPEC

ANSWER PATH

Developer question

or a pasted error
Resolve version

answer for their version
Retrieve

spec · SDK · changelog first
Generate example

in their language
Validate

against the spec before returning
Bad answer

logged as a docs defect

Solid: the grounded answer path Dashed: the loop that improves the documentation itself

The API specification and SDK source are correct by construction when generated from the running system. Prose documentation is a secondary source, and where they disagree the spec wins.

QUESTIONS

QUESTIONS — 3

No. It should absorb the repeated questions — authentication, pagination, common errors, version differences — so support engineers spend their time on the genuinely hard integration problems, which is both better use of them and the part developers most value talking to a human about.

It can generate examples and integration snippets, validated against the spec. Treat them as a starting point rather than production code — which is exactly how developers treat documentation examples anyway.

Access-controlled retrieval, so a developer sees only what their account is entitled to. That is a permission boundary in the retrieval layer rather than a prompt instruction, for the same reason as everywhere else on this site: a prompt is not a security control.

Keep reading

Support Deflection Architecture

→

30-minute technical call · no deck