Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,14 @@
"group": "Getting started",
"pages": [
"index",
"quickstart",
{
"group": "Quickstart",
"icon": "rocket",
"pages": [
"quickstart",
"quickstart/devrel"
]
},
"installation",
{
"group": "Web editor",
Expand Down
227 changes: 227 additions & 0 deletions quickstart/devrel.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,227 @@
---
title: "Developer relations"
description: "Best practices for developer relations teams using Mintlify"
icon: "users"
---

Developer relations (DevRel) teams play a crucial role in creating and maintaining documentation that serves both internal teams and external developers. This guide covers best practices for DevRel teams using Mintlify to create exceptional developer experiences.

Check warning on line 7 in quickstart/devrel.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart/devrel.mdx#L7

Use parentheses judiciously.

## Understanding your audience

DevRel teams typically serve multiple audiences with different needs and technical backgrounds:

<CardGroup cols={2}>
<Card title="External developers" icon="code">
Third-party developers integrating with your APIs, SDKs, or platform
</Card>
<Card title="Internal teams" icon="building">
Engineering, product, and support teams who need technical documentation
</Card>
<Card title="Community contributors" icon="heart">
Open source contributors and community members who help improve your docs
</Card>
<Card title="Decision makers" icon="briefcase">
Technical leaders evaluating your platform or making integration decisions
</Card>
</CardGroup>

## Content strategy for DevRel

### Start with developer journeys

Map out the complete developer experience from discovery to successful implementation:

1. **Discovery**: How developers find your documentation
2. **Evaluation**: What information they need to assess your platform
3. **Getting started**: The fastest path to a working integration
4. **Implementation**: Detailed guides for real-world use cases
5. **Troubleshooting**: Common issues and solutions
6. **Advanced usage**: Power user features and optimization

### Focus on outcomes

Structure your documentation around what developers want to achieve, not just what your product does:

<Tip>
Instead of "API Reference > Users Endpoint", try "Managing user accounts > Create and update users"

Check warning on line 46 in quickstart/devrel.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart/devrel.mdx#L46

Commas and periods go inside quotation marks.
</Tip>

## Organizing documentation for DevRel

### Use progressive disclosure

Start with high-level concepts and progressively reveal more detail:

```
Getting Started
├── Overview (what and why)
├── Quick start (fastest path to success)
├── Core concepts (essential understanding)
└── Next steps (where to go from here)

Check warning on line 60 in quickstart/devrel.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart/devrel.mdx#L60

'Next steps' should use sentence-style capitalization.

Guides
├── Common use cases
├── Integration patterns
└── Best practices

Reference
├── API documentation
├── SDK references
└── Configuration options
```

### Create clear navigation paths

Use Mintlify's navigation features to create intuitive paths:

<CodeGroup>
```json Navigation structure
{
"navigation": {
"groups": [
{
"group": "Getting started",
"pages": [
"overview",
"quickstart",
"authentication"
]
},
{
"group": "Guides",
"pages": [
"guides/webhooks",
"guides/rate-limiting",
"guides/error-handling"
]
}
]
}
}
```
</CodeGroup>

## Content creation best practices

### Write for scanning

Developers often scan documentation quickly. Use:

- **Clear headings** that describe the content
- **Bullet points** for lists and steps
- **Code examples** that work out of the box
- **Callouts** for important information

### Provide working examples

Every code example should be:

<AccordionGroup>
<Accordion title="Complete and runnable">
Include all necessary imports, configuration, and context
</Accordion>
<Accordion title="Realistic">
Use examples that reflect real-world usage patterns
</Accordion>
<Accordion title="Tested">
Verify that all code examples work with current versions
</Accordion>
</AccordionGroup>

### Use consistent terminology

Maintain a glossary of terms and use them consistently throughout your documentation:

```mdx
<Tooltip tip="A unique identifier for your application">
API key
</Tooltip>
```

## Collaboration workflows

### Work with engineering teams

- **Embed with product teams** during feature development
- **Review API designs** before implementation
- **Create documentation templates** for consistent quality
- **Establish review processes** for technical accuracy

### Gather community feedback

Use Mintlify's features to collect and act on feedback:

- Enable feedback widgets on pages
- Monitor analytics to identify problem areas
- Create feedback loops with your developer community
- Track documentation metrics alongside product metrics

## Measuring success

### Key metrics for DevRel documentation

<CardGroup cols={2}>
<Card title="Time to first success" icon="clock">
How quickly can developers achieve their first integration milestone?
</Card>
<Card title="Support ticket reduction" icon="ticket">
Are common questions being answered by documentation?

Check warning on line 168 in quickstart/devrel.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart/devrel.mdx#L168

In general, use active voice instead of passive voice ('being answered').
</Card>
<Card title="Developer satisfaction" icon="star">
Regular surveys and feedback collection
</Card>
<Card title="Content performance" icon="chart-line">
Page views, time on page, and user flows through documentation
</Card>
</CardGroup>

### Use Mintlify analytics

Leverage built-in analytics to understand how developers use your documentation:

1. **Popular content**: Which pages get the most traffic?
2. **Drop-off points**: Where do developers leave your documentation?
3. **Search queries**: What are developers looking for but not finding?
4. **User flows**: How do developers navigate through your content?

## Advanced DevRel techniques

### Create interactive experiences

Use Mintlify's components to make documentation more engaging:

<Steps>
<Step title="Add interactive API playground">
Let developers test API calls directly in your documentation
</Step>
<Step title="Include runnable code samples">
Use code groups to show examples in multiple languages
</Step>
<Step title="Embed demos and videos">
Show complex concepts with visual explanations
</Step>
</Steps>

### Build community-driven documentation

- **Enable contributions** through GitHub integration
- **Create templates** for community-contributed content
- **Establish guidelines** for community contributions
- **Recognize contributors** in your documentation

## Next steps

<CardGroup cols={2}>
<Card title="Set up analytics" icon="chart-line" href="/analytics/overview">
Track how developers use your documentation
</Card>
<Card title="Configure feedback" icon="message-circle" href="/analytics/feedback">
Collect feedback from your developer community
</Card>
<Card title="API playground setup" icon="play" href="/api-playground/overview">
Create interactive API documentation
</Card>
<Card title="Advanced components" icon="puzzle" href="/components/accordions">
Enhance your documentation with interactive elements
</Card>
</CardGroup>