Create developer documentation

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 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.

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. 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 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.

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 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 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.

• docs.json
• Directoryopenapi/!

  • platform.yaml your OpenAPI spec
• Directorycontent/!

  • index.mdx
  • quickstart.mdx
  • authentication.mdx

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.

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.

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.

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.
• 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.
• An agent Skill. reed skill generate writes a Skill pack from your spec, optionally bundling your own concept pages. See Agent Skill generation.

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 walks through the full loop, and 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 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 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 and How to maintain documentation over time 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.

Content types

Give every page one job: tutorial, how-to, reference or explanation.

Content templates

Copy-ready starting points, including a reference page.