Your API reference is your onboarding: rewriting ours from scratch

Stackwell’s analytics showed something uncomfortable: most developers who signed up had first arrived on an API reference page from a search engine, not on the homepage. The reference was generated from the schema, technically complete and almost impossible to learn from. It listed every parameter and explained none of them.

Jonah led the rewrite. Each endpoint now starts with what it is for, puts a working example first, documents every error with its cause and fix, and is tested in continuous integration so that no example can silently break. It is still generated from the schema, but the schema now carries the writing.

The talk covers the structure, the tooling and the editorial process that keeps forty engineers writing in one voice. It also covers the results: fewer support tickets about the API, longer visits to reference pages, and a measurable rise in developers who deploy on their first day.

What you will take away

• A structure for API reference pages that teaches as well as describes
• How to test documentation examples automatically, so they never drift from the API
• An editorial process that lets engineers write good reference material without a docs team