# Create developer documentation (/guides/developer-documentation)
Related: [How to create accessible documentation](/guides/accessibility.md), [Documentation content templates](/guides/content-templates.md), [Documentation content types](/guides/content-types.md), [Headless docs with a custom frontend](/guides/custom-frontend.md), [Build custom page layouts](/guides/custom-layouts.md), [Create a help center](/guides/help-center.md)
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 [#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 [#migrate-existing-documentation]
If you're creating documentation from scratch, skip to [Plan your documentation structure](#plan-your-documentation-structure).
### Audit existing content [#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-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 [#plan-your-documentation-structure]
Developer documentation typically includes several content types. Structure your navigation around how your users understand your product.
```json title="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 [#set-up-your-api-reference]
If you have an API, generate an interactive reference from your OpenAPI specification.
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
```
Reference your OpenAPI file in your `docs.json` configuration.
```json title="Configuration example"
{
"openapi": "openapi.yaml"
}
```
Add the endpoints to your `docs.json` navigation. See [OpenAPI setup](/api-playground/openapi-setup) for configuration options.
```json title="Navigation example"
{
"group": "API Reference",
"pages": [
"api-reference/overview",
"api-reference/users/list-users",
"api-reference/users/get-user",
"api-reference/users/create-user"
]
}
```
## Set up the assistant [#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 [#set-up-versioning]
If you maintain multiple API versions, configure versioning so developers find documentation for their version.
```json title="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 [#connect-to-your-repository]
Install the Mintlify [GitHub App](/deploy/github) to keep documentation in sync with your codebase and enable contributions.
Link your GitHub repository in the [dashboard](https://app.mintlify.com). This enables automatic deployments when you push changes.
Set your production branch and enable preview deployments for pull requests. This lets you review documentation changes before they go live.
If you use GitLab, see [GitLab](/deploy/gitlab) for configuration instructions.
## Maintain your documentation [#maintain-your-documentation]
Developer documentation needs regular updates so that information is accurate and usable.
Update your OpenAPI specification whenever you release changes. If you generate your specification from code, automate this in your release process.
Review code examples when you release new SDK versions or product updates. Outdated examples cause integration failures and support requests.
Document breaking changes, new features, and deprecations. Developers rely on changelogs to understand what changed between versions. See [Changelogs](/create/changelogs) for more information.
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.
## Next 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.