Developer documentation

Developer documentation has a specific shape. The best-in-class sites — Stripe, Twilio, Linear, Vercel, Supabase — all follow roughly the same structure because it matches the way developers evaluate, adopt, and operate a platform. Missing any of the seven core sections loses you users at a specific stage of the funnel.

This is the end-to-end recipe. Apply it as a gap analysis against your current docs, a blueprint for a new one, or a prioritisation list.

The seven sections every dev doc site needs

How each section maps to Diátaxis

See content types for the framework.

Section order in the sidebar

Top-to-bottom, matches reader journey:

├── Get Started
│   ├── Introduction
│   ├── Quickstart
│   └── Concepts
├── Guides            (how-to section)
│   ├── Authenticate
│   ├── Handle webhooks
│   ├── Pagination
│   └── ...
├── API Reference     (separate tab — can be huge)
├── SDKs              (separate tab — one per language)
└── Resources
    ├── Changelog
    ├── Migration
    └── Status

Readers land on Introduction → Quickstart → (when stuck) Guides → (when operating) API Reference + SDKs → (at version bumps) Changelog. Mismatched order means readers can't find their next step.

Page budget for each section

Rough sizing for a mid-sized dev platform:

Anything more is probably sprawl. Anything less is probably under-documented.

Day 1 — minimum viable dev docs

Ship these 8 pages before launch:

8 pages is enough to launch. Ship. Iterate.

First quarter — expand the core

After launch, add 10-20 more pages over ~3 months:

• More concepts — one per primary object (users, sessions, webhooks, subscriptions, whatever).

• More how-tos — one per top-10 support ticket theme. Support tickets are the canonical priority list.

• SDK docs per language — TypeScript first (widest audience for most dev tools), then Python, then Go / Ruby / others by user demand.

• Common-case tutorials — a 30-minute "build X with Acme" tutorial for the top use case. Longer than a quickstart, more narrative, results in a working sample repo.

Second quarter — depth and polish

By month 6:

• Migration guides for every breaking change shipped so far.

• Webhooks deep dive — signature verification, retries, payload schemas.

• Rate limit docs — actual numeric limits, headers returned, back-off strategy.

• Error code exhaustive list — every error code your API can return, grouped by category.

• Data model reference — object schemas beyond what the API reference covers.

• Integration recipes — "Using Acme with Next.js", "Using Acme with Django" — code-heavy tutorials.

Dev docs patterns that rank

Three specific patterns that consistently rank well in Google + LLM answer boxes:

Pattern 1: "Install in 30 seconds" hero

## Install

<CodeGroup>
```bash npm
npm install @acme/sdk
```

```bash yarn
yarn add @acme/sdk
```

```bash pnpm
pnpm add @acme/sdk
```
</CodeGroup>

## Send your first request

```typescript
import Acme from "@acme/sdk";

const acme = new Acme({ apiKey: process.env.ACME_KEY });
const result = await acme.users.list();
console.log(result.data.length);
```

Above the fold: install, one API call, one log. Readers see they can be productive in 30 seconds before scrolling to the details.

Pattern 2: Error as entry point

Create a page per HTTP error code your API returns. Developers Google error messages verbatim. The page should include the message, the cause, and the fix.

---
title: "Error: invalid_api_key"
description: "401 response when the Authorization header is missing, malformed, or references a revoked key. Resolution steps below."
---

HTTP 401 returned when the `Authorization` header fails server-side
validation. Four common causes:

1. **Missing `Bearer` prefix**: The header must be
   `Authorization: Bearer sk_live_...`, not `Authorization: sk_live_...`.
2. **Revoked key**: Check the dashboard for key status. Rotate if
   revoked.
3. **Wrong environment**: `sk_test_...` keys only work against test-
   mode endpoints (`api-test.acme.com`), not production.
4. **Whitespace**: Trailing newline or space in the env var. Trim
   before using.

This page ranks for "acme invalid_api_key" and every variant. One page per error code = compound SEO wins over time.

Pattern 3: "X in Y" recipe pages

Using Acme with Next.js
Using Acme with Vercel Functions
Using Acme with Django
Using Acme with Laravel
Using Acme with Rails

Each page is a focused integration walkthrough. Developers search "acme next js tutorial" — your recipe page is the top hit. Compounds over time as you cover more frameworks.

API reference discipline

The reference pages auto-generate from your OpenAPI spec. Quality comes from spec quality:

• Every operation has a description, not just a summary.

• Every parameter has a description, type, required, default.

• Every response has at least one example that looks like real data.

• Every error status has its own response entry with the Error schema.

• operationIds are human-readable — listUsers, createPayment, not op_423.

See multiple responses, complex types, and SDK examples for the MDX-component side. The OpenAPI spec discipline compounds into docs quality.

SDK documentation strategy

For each supported SDK:

1. Install page — package manager tabs, version constraints, peer deps.

2. Getting started — mirrors the API quickstart but SDK-specific.

3. Core patterns — common usage patterns with idiomatic code.

4. Type reference — for typed languages (TS / Python Pydantic / Go), link to generated type docs or re-document in the site.

5. Error handling — SDK-specific exception hierarchy.

Don't write 5 pages per SDK if you have 8 SDKs — that's 40 pages for lower-priority languages. Typescript + Python full 5-page treatment, Go + Ruby + Java 2-page abbreviated, other SDKs 1-page install + link-to-github-readme.

Migration guides — the underrated section

Most dev docs under-invest here. Every breaking change needs:

• What changed (bullet list of renames / removals / behaviour changes).

• Why (one paragraph — readers want to know if it affects them).

• Timeline (deprecation date, sunset date, hard removal date).

• Step-by-step upgrade with before / after code diffs.

• Edge cases (what if you're combining old X with new Y during migration).

Good migration guides reduce support load more than any other type of docs.

The "what next" call-to-action

Every page should end with a specific next step. Not "Learn more about Acme" — a literal next page:

## Related

- [Next: handle webhooks](/guides/webhooks)
- [Reference: API rate limits](/api/rate-limits)
- [Deep dive: why Acme uses per-key rate limits](/concepts/rate-limit-design)

Readers ALWAYS have a next step. Docs that end flat lose readers to bounce.

Common developer-docs mistakes

Related

• Content types — Diátaxis framework for mode choices

• Style and tone — voice rubric per section

• Understand your audience — evaluators / implementers / operators personas

• SEO for docs — ranking signals for each section type

• API reference overview — auto-generation mechanics

• Changelogs — the <Update> component