Create developer documentation
Build developer documentation that helps engineers integrate with your APIs, SDKs, and tools, including quickstarts, references, and guides.
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 from OpenAPI specifications that let developers test endpoints in your documentation.
- Code blocks with explanations: The assistant explains code examples in context, helping developers understand implementation details.
- Git sync: Keep documentation in sync with your codebase using GitHub, GitLab, or Bitbucket Cloud.
- Versioning: Maintain documentation for multiple versions so developers on older versions can still find accurate information.
Prerequisites
Section titled “Prerequisites”If you haven't created a Mintlify project yet, see the 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
Section titled “Migrate existing documentation”If you're creating documentation from scratch, skip to Plan your documentation structure.
Audit existing content
Section titled “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
Section titled “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
Section titled “Plan your documentation structure”Developer documentation typically includes several content types. Structure your navigation around how your users understand your product.
{
"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 for more configuration options.
Set up your API reference
Section titled “Set up your API reference”If you have an API, generate an interactive reference from your OpenAPI specification.
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.mdxConfigure the spec in docs.json
Reference your OpenAPI file in your
docs.jsonconfiguration.Configuration { "openapi": "openapi.yaml" }
Set up the assistant
Section titled “Set up the assistant”The assistant helps developers find answers and understand code examples. Configure it from your dashboard.
- Sample questions: Add developer-focused questions like "How do I authenticate API requests?" or "Show me how to handle webhooks."
- Code explanations: The assistant can explain code blocks in context when developers ask questions about specific examples.
Set up versioning
Section titled “Set up versioning”If you maintain multiple API versions, configure versioning so developers find documentation for their version.
{
"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 for more information.
Connect to your repository
Section titled “Connect to your repository”Install the Mintlify GitHub App to keep documentation in sync with your codebase and enable contributions.
Connect your repository
Link your GitHub repository in the dashboard. This enables automatic deployments when you push changes.
Configure branch settings
Set your production branch and enable preview deployments for pull requests. This lets you review documentation changes before they go live.
Maintain your documentation
Section titled “Maintain your documentation”Developer documentation needs regular updates so that information is accurate and usable.
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.
Update code examples
Review code examples when you release new SDK versions or product updates. Outdated examples cause integration failures and support requests.
Maintain a changelog
Document breaking changes, new features, and deprecations. Developers rely on changelogs to understand what changed between versions. See Changelogs for more information.
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 for more information.
Next steps
Section titled “Next steps”Your developer documentation is ready to launch. After deploying:
- Announce the documentation to your developer community.
- Monitor search patterns and assistant conversations for gaps.
- Set up a process to update docs with each API release.
- Gather feedback from developers to improve content over time.