mintlify__docs/guides/developer-documentation.mdx

---
title: "Create developer documentation"
sidebarTitle: "Developer documentation"
description: "Build developer documentation that helps engineers integrate with your APIs, SDKs, and tools, including quickstarts, references, and guides."
keywords: ["developer documentation", "API documentation", "SDK docs", "technical documentation", "developer portal"]
---

Developer documentation helps people understand and integrate with your product. Good documentation helps people do more with your product, reduces support burden, speeds up adoption, and improves developer experience.

Mintlify provides infrastructure built for developer documentation.

- **API reference generation**: Generate interactive [API references](/api-playground/overview) from OpenAPI specifications that let developers test endpoints in your documentation.
- **Code blocks with explanations**: The [assistant](/assistant/index) explains code examples in context, helping developers understand implementation details.
- **Git sync**: Keep documentation in sync with your codebase using [GitHub](/deploy/github) or [GitLab](/deploy/gitlab).
- **Versioning**: Maintain documentation for multiple [versions](/organize/navigation#versions) so developers on older versions can still find accurate information.

## Prerequisites

If you haven't created a Mintlify project yet, see the [Quickstart](/quickstart) to deploy your site.

- Your API specification in OpenAPI format (if documenting an API)
- A Git repository for your documentation
- Admin access to your Mintlify organization

## Migrate existing documentation

If you're creating documentation from scratch, skip to [Plan your documentation structure](#plan-your-documentation-structure).

### Audit existing content

Review your current documentation to understand what you have and what you need to migrate.

- **API reference**: Is it generated from a spec or hand-written? What endpoints do you document?
- **Guides and tutorials**: What integration guides exist? Are they current?
- **Code examples**: What languages and frameworks do you use?
- **SDK documentation**: Do you have separate documentation for each SDK?
- **Changelog**: Do you maintain a changelog or release notes?
- **Metadata**: Do you have metadata for your content like dates, authors, and tags?

### Export your existing content

- Export to **Markdown** for the simplest migration to Mintlify.
- Export **OpenAPI specs** for API reference content.
- Export to **HTML** if Markdown isn't available, then convert to Markdown.

## Plan your documentation structure

Developer documentation typically includes several content types. Structure your navigation around how your users understand your product.

```json docs.json example
{
  "navigation": {
    "groups": [
      {
        "group": "Get Started",
        "pages": [
          "introduction",
          "quickstart",
          "authentication"
        ]
      },
      {
        "group": "Guides",
        "pages": [
          "guides/webhooks",
          "guides/error-handling",
          "guides/rate-limits",
          "guides/pagination"
        ]
      },
      {
        "group": "API Reference",
        "pages": [
          "api-reference/overview",
          "api-reference/users",
          "api-reference/orders",
          "api-reference/products"
        ]
      },
      {
        "group": "SDKs",
        "pages": [
          "sdks/javascript",
          "sdks/python",
          "sdks/go"
        ]
      }
    ]
  }
}
```

See [Navigation](/organize/navigation) for more configuration options.

## Set up your API reference

If you have an API, generate an interactive reference from your OpenAPI specification.

<Steps>
  <Step title="Add your OpenAPI spec">
    Add your OpenAPI specification file to your project. You can use YAML or JSON format.

    ```text
    your-project/
    ├── docs.json
    ├── openapi.yaml
    └── api-reference/
        └── overview.mdx
    ```
  </Step>

  <Step title="Configure the spec in docs.json">
    Reference your OpenAPI file in your `docs.json` configuration.

    ```json Configuration example
    {
      "openapi": "openapi.yaml"
    }
    ```

    
  </Step>

  <Step title="Add endpoints to navigation">
    Add the endpoints to your `docs.json` navigation. See [OpenAPI setup](/api-playground/openapi-setup) for configuration options.

    ```json Navigation example
    {
      "group": "API Reference",
      "pages": [
        "api-reference/overview",
        "api-reference/users/list-users",
        "api-reference/users/get-user",
        "api-reference/users/create-user"
      ]
    }
    ```
  </Step>
</Steps>

## Set up the assistant

The assistant helps developers find answers and understand code examples. Configure it from your [dashboard](https://app.mintlify.com/products/assistant/settings).

{/* vale Mintlify.FirstPerson = NO */}
- **Sample questions**: Add developer-focused questions like "How do I authenticate API requests?" or "Show me how to handle webhooks."
{/* vale Mintlify.FirstPerson = YES */}
- **Code explanations**: The assistant can explain code blocks in context when developers ask questions about specific examples.

## Set up versioning

If you maintain multiple API versions, configure versioning so developers find documentation for their version.

```json Versioning example
{
  "versions": ["v2", "v1"],
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "version": "v2",
        "pages": ["v2/api-reference/users"]
      },
      {
        "group": "API Reference",
        "version": "v1",
        "pages": ["v1/api-reference/users"]
      }
    ]
  }
}
```

See [Versions](/organize/navigation#versions) for more information.

## Connect to your repository

Install the Mintlify [GitHub App](/deploy/github) to keep documentation in sync with your codebase and enable contributions.

<Steps>
  <Step title="Connect your repository">
    Link your GitHub repository in the [dashboard](https://app.mintlify.com). This enables automatic deployments when you push changes.
  </Step>

  <Step title="Configure branch settings">
    Set your production branch and enable preview deployments for pull requests. This lets you review documentation changes before they go live.
  </Step>
</Steps>


<Note>
  If you use GitLab, see [GitLab](/deploy/gitlab) for configuration instructions.
</Note>

## Maintain your documentation

Developer documentation needs regular updates so that information is accurate and usable.

<Steps>
  <Step title="Keep the API reference current">
    Update your OpenAPI specification whenever you release changes. If you generate your specification from code, automate this in your release process.
  </Step>

  <Step title="Update code examples">
    Review code examples when you release new SDK versions or product updates. Outdated examples cause integration failures and support requests.
  </Step>

  <Step title="Maintain a changelog">
    Document breaking changes, new features, and deprecations. Developers rely on changelogs to understand what changed between versions. See [Changelogs](/create/changelogs) for more information.
  </Step>

  <Step title="Monitor feedback">
    Review assistant conversations and search analytics to identify gaps in your documentation. If developers repeatedly ask about the same topic, improve that section. See [Maintenance](/guides/maintenance) for more information.
  </Step>
</Steps>

## Next steps

Your developer documentation is ready to launch. After deploying:

1. Announce the documentation to your developer community.
2. Monitor search patterns and assistant conversations for gaps.
3. Set up a process to update docs with each API release.
4. Gather feedback from developers to improve content over time.