Turning a customer's API spec into a published docs site

Jesse James Richard
|
Jul 21, 2026
|
5 min read
#Signature
#APIs & MCP
#AI & Agents

A company with an API has two documents to keep. They are not equally hard. One is the API reference, the exhaustive list of every endpoint and every field. That one is mechanical. The specification the API already publishes contains all of it. Turning it into reference pages is a solved problem that a dozen tools do well. The other is the SDK documentation. That one is the product.

Almost no developer calls a raw endpoint. They install the company's client library, its SDK, then call a method on it. What they need documented is that library. What each of its methods does, how to call it in the language they write, and how the methods fit together, because real work is never a single call. That documentation is written by hand today, which means it lags the library. It is the first thing a developer opens, and what they most resent when it is wrong. A developer decides whether to build on an API in the first hour, and decides it from the docs. Good SDK documentation is the difference between a developer who ships something and one who gives up and leaves. That is why companies pay for it, and why it is strange that it is the one they most often neglect.

Reading the SDK to write its docs

This platform generates that documentation. How it does it is the point. It does not generate an SDK from the specification, which is a different and more mechanical job that other vendors sell. It goes the other direction. The company points the platform at its own SDK, the library it already ships. The platform reads that library and writes the documentation for it.

A model reads the actual source. It finds each method the library exposes and works out which endpoint the method calls underneath. It writes a plain description of what the method is for, in more than one language, so that the docs are not English by default. It writes a runnable example of calling the method, in TypeScript and in Python. And it does the thing a reference page cannot. It works out how the methods depend on one another, and writes the example as the sequence a developer would really run, not the single bare line a reference would show.

A generated SDK reference page. One method, its description, and a runnable example in both languages, inline.

Why only a model can do it

None of that is a template. A template can turn a specification into a reference table, because the specification is already structured to become one. A template cannot read an arbitrary client library, in whatever shape its authors gave it, and say what its methods are for. It cannot infer that one call feeds another. It cannot write an idiomatic example in two languages from the code alone. The tools that sell SDK generation work forward, from a specification to a fresh library, by template. This works backward, from a library that already exists to the documentation it never had. The forward direction is a transform. The backward direction is comprehension. Only comprehension needs a model.

Spec to SDK
SDK to docs

Starts from

An API specification

A library that already ships

Produces

A fresh SDK, generated

The documentation it never had

The work

A transform

Comprehension

Needs a model

No, a template will do

Yes, only a model can

It also means the docs stay current. Hand-written SDK documentation is a copy of the library kept beside it. The copy falls behind the moment the library moves. These docs are generated from the library. When the SDK changes, the platform reads it again and rewrites the parts that moved. The documentation is a function of the code, recomputed when the code changes, not a second copy to keep in step by hand.

The rest comes along for free

Around the SDK documentation, the mechanical parts arrive at no added cost. The API reference renders from the specification, each endpoint with a copyable request. It all publishes as a real site, on the company's own domain, in its own brand, through the same system that builds its marketing pages. The chatbot that answers questions elsewhere on the site answers them about the SDK too, because the generated docs are part of what it has read. Those are worth having. They are not the reason to build this.

What the product actually is

SDK documentation is what companies pay a developer-experience vendor for. It is also what they most often let fall behind, because it is the most tedious thing to keep current by hand. Here it is generated from the library the company already ships, kept in sync with it, and published on the company's own site. Most software companies ship an SDK. Every one of them needs it documented. Documenting an arbitrary SDK well is something only a model can do. That is the product. The branded site it lives on is where it ships.

Have questions?

If you're interested in my work or Giant Context, contact me!

Contact Jesse
More
Sitemap
Privacy Policy
Terms of Service
Cookie Policy
Hosted on
Turning a customer's API spec into a published docs site | Jesse James Richard