---
title: Create developer documentation
description: Plan, build and maintain documentation that engineers use to integrate with your API, SDKs and tools.
---

Developer documentation exists so that engineers can integrate with your product without
asking you how. Good developer docs speed up adoption, cut support load, and decide whether
an evaluation turns into an integration. Bad ones send people to a competitor whose
quickstart worked.

This guide walks through building developer docs on Reed: migrating what you have,
structuring it, generating the API reference from your spec, and keeping all of it current.

## What Reed gives you, and what it does not

Reed is a compiler. You run it in your terminal and in CI, and it turns `docs.json` and a
directory of MDX into a static site you host yourself. For developer docs, that means:

- **An API reference from your OpenAPI spec.** Name a spec in `docs.json` and Reed
  generates one endpoint page per operation, each with HTTP request examples in five
  languages derived from the spec. See [OpenAPI specs](/docs/api/specs).
- **Docs that live in your repository.** Your pages are MDX files and your config is one
  JSON file. They go through the same branches, reviews and CI as your code, on whatever
  git host you already use.
- **Surfaces for agents, from the same source.** Every build writes `llms.txt` and a
  markdown mirror of each page. `reed mcp generate` and `reed skill generate` turn your
  spec into an MCP server and an agent Skill you own. See
  [One source, every surface](/docs/derived/overview).

Three things developer-docs platforms often advertise are not here, and it is better to
know that before you plan around them:

- **No "try it" console.** Generated endpoint pages document requests; they do not send
  them from the browser.
- **No SDK generation.** The request examples call your HTTP API directly. Reed does not
  generate a client library, and it will not render install instructions for a package
  that does not exist.
- **No versioned documentation.** `docs.json` accepts a `versions` key and ignores it.

SDK generation and versioned documentation are on the [roadmap](/docs/roadmap). An API
playground is not: there is no try-it console today and none is planned. Where these gaps
matter, this guide says what to do instead.

## Prerequisites

- Reed installed, and a project you can build. The [Quickstart](/docs/quickstart) takes
  five minutes.
- A git repository for the docs. It can be its own repository or a directory in your
  product's.
- Your API specification in OpenAPI format, if you are documenting an API.

There is no account to create and no organization to be an admin of. If you can run
`reed build`, you have everything Reed needs.

## Migrate existing documentation

If you are starting from nothing, skip to [planning the structure](#plan-your-documentation-structure).

### Audit what you have

Before you move anything, write down what exists. The list tells you how big the migration
is and gives you a checklist to confirm nothing was left behind.

- **API reference.** Is it generated from a spec, or hand-written? Which endpoints does it
  cover, and does that match what the API actually serves?
- **Guides and tutorials.** Which integration guides exist? Which still work?
- **Code examples.** Which languages and frameworks do they use? Who last ran them?
- **SDK documentation.** Is there a separate set of pages per SDK?
- **Changelog.** Do you keep release notes, and where?
- **Metadata.** Do pages carry dates, authors or tags you need to keep?

Expect the audit to surface pages nobody owns and examples nobody has run in a year.
Migration is the cheapest moment to delete them.

### Export your content

- **Markdown** is the simplest path. Reed pages are MDX, and most Markdown is valid MDX.
- **OpenAPI specs** carry your API reference. Export the spec, not the rendered pages; Reed
  regenerates the pages from it.
- **HTML** works when Markdown is not available. Convert it with a tool such as Pandoc,
  then clean up what the conversion gets wrong.

If your docs are on Fern, `reed import --from fern` converts the project for you. It is the
only importer Reed has. [Migrating from Fern](/docs/migrate/fern) covers what it converts
and what it drops.

## Plan your documentation structure

Developer docs usually hold four kinds of content: getting started, task guides, reference
and SDK pages. Structure navigation around how an engineer adopts your product, not around
how your teams are organized. [How to structure documentation navigation](/docs/guides/navigation)
covers the reasoning; here is what it looks like in `docs.json`:

```json
{
  "api": { "specs": { "platform": "openapi/platform.yaml" } },
  "navigation": {
    "tabs": [
      {
        "label": "Docs",
        "groups": [
          { "label": "Get started", "pages": ["index", "quickstart", "authentication"] },
          {
            "label": "Guides",
            "pages": [
              "guides/webhooks",
              "guides/error-handling",
              "guides/rate-limits",
              "guides/pagination"
            ]
          },
          { "label": "SDKs", "pages": ["sdks/typescript", "sdks/python"] }
        ]
      },
      {
        "label": "API reference",
        "groups": [
          {
            "label": "API reference",
            "pages": [{ "label": "API reference", "api": true, "spec": "platform" }]
          }
        ]
      }
    ]
  }
}
```

Two things about this shape are Reed rules, not style choices:

- **The generated reference gets a tab of its own.** An API entry must be the only page in
  its group, and that group the only group in its tab. Your authentication guide cannot sit
  in the same group as the generated endpoints, so it lives under Get started and links
  across.
- **Every page must be listed.** A file in `content/` that no navigation entry names fails
  the build. Every new page arrives with a placement decision.

The SDK pages in the example are hand-written. Include them only if you publish SDKs. Reed
generates none, so an SDK group describes packages your team builds and releases.

## Set up your API reference

### Add the spec to your project

Put the spec file in the repository, conventionally under `openapi/`. YAML and JSON both
work. Reed reads it at build time and never modifies it.

<Files>
  <File name="docs.json" />
  <Folder name="openapi" defaultOpen>
    <File name="platform.yaml" comment="your OpenAPI spec" />
  </Folder>
  <Folder name="content" defaultOpen>
    <File name="index.mdx" />
    <File name="quickstart.mdx" />
    <File name="authentication.mdx" />
  </Folder>
</Files>

### Declare it and mount it

Name the spec under `api.specs`, then reference the name from an API entry in
`navigation`, as in the example above. Reed synthesizes one endpoint page per operation.
There is no MDX file for them, and you do not write one. Run `reed check` to confirm the
spec name resolves.

A project with two APIs declares two specs and gets two tabs. That is the intended shape.

### Choose the snippet languages

Every generated endpoint page shows the request in five languages: `curl`, `fetch`,
`python-requests`, `python-httpx` and `go-nethttp`. Narrow the set, or pick the default
tab, with `snippets`:

```json
{
  "snippets": {
    "languages": ["curl", "fetch", "python-requests"],
    "default": "curl"
  }
}
```

The five are renderings of one request derived from the spec, so they cannot drift apart.
When an operation needs an example a mechanical derivation cannot produce — pagination, a
realistic payload, a required call order — write it as `x-codeSamples` in the spec. Your
samples always win over generated ones. See [Code snippets](/docs/api/snippets).

### Document what the spec does not cover

Some interfaces have no spec: a webhook payload, a CLI, a config file. Document them by
hand with `ParamField` and `ResponseField`, which give every parameter and field the same
name, type, default and description. Generated endpoint pages have their own layout, so
link from them to the hand-written pages rather than trying to mix the two. See
[API reference components](/docs/reference/components/api).

<Note>
  Readers cannot send a request from a Reed endpoint page. If your API is easy to call with
  a test key, the next best thing is a quickstart that does exactly that with `curl` in the
  first five minutes.
</Note>

## Serve developers who read through an agent

Many engineers now meet your docs through an AI coding assistant before they meet your
site. Reed has no assistant widget on the page. It gives the agent your docs directly:

- **`llms.txt` and markdown mirrors.** Every build writes your whole site as one plain-text
  file plus a `.md` copy of each page. No configuration. See [llms.txt](/docs/derived/llms-txt).
- **An MCP server.** `reed mcp generate` writes the source of an MCP server for your API into
  your repository. You own it and host it. See [MCP server generation](/docs/derived/mcp).
- **An agent Skill.** `reed skill generate` writes a Skill pack from your spec, optionally
  bundling your own concept pages. See [Agent Skill generation](/docs/derived/skill).

Code blocks still need to explain themselves. Put the explanation in the prose around each
example, where both people and agents read it.

## Handle more than one version

Reed builds one version of your docs. There is no version switcher, and a `versions` block
in `docs.json` is silently ignored.

If you must keep an old major version readable, the workable arrangement is a second Reed
build from a long-lived branch, deployed at its own `base` such as `/docs/v1`. Reed treats
the two as unrelated sites: no shared navigation, no cross-version search. For most APIs a
cheaper answer is better — document the current version, and keep a migration guide and a
changelog entry for every breaking change.

## Connect your docs to your repository

Reed does not watch your repository. Nothing builds when you push unless your CI does it.

1. **Run `reed check` on every pull request.** It is offline and fast, and it fails on a
   page id that resolves to nothing, a bad spec reference, or an invalid config.
2. **Build previews in CI if reviewers need them.** Upload the built site to a host that
   supports per-branch previews, such as Cloudflare Pages, Netlify or Vercel, and post the
   URL on the pull request.
3. **Deploy from main only.** Build and upload from a clean checkout of the main branch, and
   check the live site for a phrase from this build rather than trusting the exit code.

[Git workflows for documentation](/docs/guides/git-workflows) walks through the full loop,
and [Deploy](/docs/ship/deploy) covers the upload.

## Maintain your documentation

Developer docs go stale on a schedule set by your release cadence. Tie the two together.

### Keep the API reference current

Update the spec whenever the API changes. If you generate the spec from code, make that
part of your release pipeline so the reference is rebuilt from the same commit that ships
the change. The generated pages then cannot fall behind.

### Keep code examples working

Review hand-written examples and `x-codeSamples` whenever you ship a new SDK version or
change a request shape. An outdated example is worse than none: it fails in the reader's
terminal and becomes a support ticket.

### Keep a changelog

A page with `type: changelog` in its frontmatter and one dated `##` heading per release is
a changelog. Record breaking changes, new features and deprecations. Engineers read it to
decide whether upgrading is safe. Reed's own [changelog](/docs/changelog) is built this
way. There is no RSS feed.

### Watch for gaps

Reed collects nothing about your readers. Page views come from one of the six
[analytics providers](/docs/site/analytics) you can configure. Search runs in the reader's
browser, so there is no log of what people searched for. The richest signal is usually your
support queue: every ticket about something the docs cover is a page that failed. Give
readers a way to report problems, such as an issue link in `footer.columns`.
[How to measure and improve documentation quality](/docs/guides/improving-docs) and
[How to maintain documentation over time](/docs/guides/maintenance) go deeper.

## Next steps

Once the site is live:

1. Announce it where your developers already are, and link to it from your product.
2. Watch page views and support tickets for topics that pull traffic or generate questions.
3. Make a docs update part of every API release, in the same pull request where possible.
4. Collect feedback from developers and act on the specific, fixable reports first.

<CardGroup cols={2}>
  <Card title="Content types" href="/docs/guides/content-types">
    Give every page one job: tutorial, how-to, reference or explanation.
  </Card>
  <Card title="Content templates" href="/docs/guides/content-templates">
    Copy-ready starting points, including a reference page.
  </Card>
</CardGroup>