mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
225 lines
7.7 KiB
Plaintext
225 lines
7.7 KiB
Plaintext
---
|
|
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), [GitLab](/deploy/gitlab), or [Bitbucket Cloud](/deploy/bitbucket).
|
|
- **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.
|