API and developer docs

Developer documentation has two halves that need different handling. The API reference lists every endpoint, parameter and response, and should match the API exactly. The guides explain how to authenticate, how to complete common tasks and how to recover from errors, and are written by people. Tools in this category help with one or both halves, and the best setups keep the reference generated from a single source of truth while giving writers freedom on the guides.

For the reference, most tools start from an OpenAPI definition, a machine-readable description of your API. They read the file and build pages for each endpoint, often with a console where a developer can enter values and send a test request from the page. Some also generate client libraries in several languages from the same file. The quality of the output depends on the quality of the definition, so descriptions, examples and error codes in the file are worth the effort.

For the guides, the big choice is between a hosted platform and a docs-as-code setup. Hosted platforms give you an editor in the browser, a ready-made site, search, analytics and often an AI assistant, with little engineering work. Docs-as-code means writing Markdown or MDX files in a Git repository, reviewing them in pull requests and building the site with a static site generator. It keeps docs close to the code and lets engineers contribute easily, at the cost of someone maintaining the build.

Many tools now sit in between: content lives in Git, but a hosted service builds and serves the site, with a visual editor for people who prefer not to touch files. When comparing them, ask how two-way sync works if both writers and engineers edit, and what happens when the two edit the same page.