What era are your docs in?

My kids have been teaching me about aura farming, and it’s got me thinking.

Most API docs are stuck in the basic tractor era. Here’s what I mean:

Shovel Era

No docs. Developers have to read the source or setup MitM proxies to reverse engineer how your mobile app talks to your API.

Plow Era

Developers get a flat HTML API reference: endpoints, parameters, maybe some descriptions. POST /v1/charges. Figure out the rest yourself.

Basic Tractor

API refs include cURL examples and maybe some generic code-snippets (think requests in Python or fetch in TypeScript): This is a little better, but developers either need to translate from cURL to their language or they still need to implement their own clients.

Modern Tractor

API references include code snippets that show how to make the API call with first-party SDKs. In addition to seeing something like POST /v1/fine_tunes developers also see const ft = await client.fine_tunes.create(...) in the example API request code snippet. This is the experience we’ve come to love from the Stripe API ref over the past few years.

GPS-Guided Harvester

Stainless Docs Platform pushes into a new era with SDK-native docs. Two documentation lineages are merging:

• the godoc-style/crate-style/DocC-style precision of auto-generated SDK references
• the Stripe-like clarity of human-crafted API guides with SDK code snippet examples

The result is this new synthesis where docs teach developers how to use the SDK and how to use the API.

What’s next?

One of the really exciting benefits of using the same system for SDK codegen and SDK-native docs comes when combined with MCP. Using MCP servers to surface docs and code examples in a specific programming language help ensure that assistants are writing code with the right versions of your SDKs and APIs (not what’s on StackOverflow from 10 years ago).

Stainless Docs Platform with SDK-native API docs is in early access! Give it a shot.