A getting-started guide and reference for an API or tool, on one page with a sidebar and copyable code.
Good documentation gets a developer to a working request before they've decided whether they like your API. Open the docs for Sheetfed, a made-up service that turns HTML into PDFs, to see that done on a single page with a sidebar. Its structure will fit most small APIs. The requests and responses have to come from yours.
Who it's for
A developer or a small team with an API, a command-line tool or an internal service that other developers have to use: a partner's engineers, next month's new hire. You send the link along with the API key, and again each time someone asks a question the page already answers.
One page suits something with up to a dozen endpoints or commands. Past that, or once you need versions and search, use a docs generator that builds from your source. A published page also doesn't change when the code does. Whoever ships a change to the API replaces the page.
What a good one contains
- One sentence on what it does, and the base URL. Both sit above Sheetfed's quickstart. Someone is always hunting for that URL.
- A quickstart that ends in a result. Four steps: set a key, start a render, check on it, download the PDF. Each shows the exact command, and steps two and three show the exact response.
- Samples that agree with each other. The id in the first response,
rnd_7Hq2Lx, is the id in the next two requests. Someone pasting them in order never meets a value from nowhere.
- A copy button on every block. Retyping a curl command by hand is how the stray quote gets in.
- Reference as tables. Endpoints get a method, a path and one line each. Options get a type and a default.
- Errors with what to do next. Eight are listed, from 400 to 500, and each says whether to fix the request, wait or try again.
- Limits as plain numbers. 60 requests a minute, 2 MB of HTML, PDFs kept for 24 hours. Leave them out and developers meet them in production.
- A date. "Updated January 19, 2027" tells a reader how far to trust the page.
Keep it true
Run every sample against the real thing before you publish, and paste the real output. A quickstart that fails on step two loses the developer for good. Use a test key in samples, never a live one, because anyone can read an open page.
Write for the reader who lands with one question. Give each section a plain heading, and repeat the authorization header in every request, so any block works when it's copied alone.
How to send it
As an open link. Docs get pasted into tickets and chat threads, so the link should open for anyone. If the API is internal, limit the page to your company's domain instead.
Every page you publish gets one link that opens in any browser. You choose who can open it: anyone with the link, anyone with the password, or only the people and company domains you name, who sign in with Google or Microsoft. Change the page later and the link stays the same.
