How to write docs for a SaaS API: a four-part structure that works
· 7 min read
To write docs for a SaaS API, split them into four parts: a reference generated from an OpenAPI file, a quickstart that gets a first call working, a handful of how-to guides for real tasks, and a short explanation page for concepts such as auth and rate limits. Keep each part to one job. Most weak API docs fail because one page tries to be all four.
This post uses two primary sources, the Diátaxis documentation framework and the OpenAPI Initiative's introduction, both read on 15 November 2026. Suggestions that come from us rather than those sources are marked.