A practical guide to serving different audiences without maintaining multiple doc sites
Here's a challenge I didn't expect when I started documenting an AI platform: different customers need different documentation.
Some customers want security details, compliance information, and deployment guides. Others want quick starts and code examples. Some customers use specific features that others never touch.
The obvious solution? Multiple documentation sites. One for each customer type, one for each use case.
The obvious solution is also a maintenance nightmare.
Here's how I actually solved it using Mintlify's group-based access control, serving different audiences from a single doc site without losing my mind.
The Problem: One Product, Many Audiences
When you're documenting a platform with diverse customers, you quickly realize that "one size fits all" documentation doesn't work.
The challenges I faced:
- Different companies needed different content based on their use cases
- Different use cases required different getting-started paths
- Some features were only relevant to specific customer segments
- Maintaining multiple doc sites would mean duplicating shared content across all of them
I needed a way to personalize the documentation experience without creating separate silos.
The Primary Solution: Group-Based Access Control
For truly customer-specific content that should only be visible to certain users, Mintlify supports group-based access control. This is the approach I went with.
How it works:
- Enable authentication (OAuth or JWT)
- Your auth system returns user groups
- Pages can be restricted to specific groups
Example: Restricting a page to specific users
---
title: "Advanced Configuration Guide"
groups: ["pro-users"]
---
# Advanced Configuration Guide
This guide covers features available to pro users...
Users not in the "pro-users" group won't see this page. They'll get a 404 if they try to access it directly.
Example: User info returned by your auth system
{
"groups": ["pro-users", "beta-testers"],
"expiresAt": 1735689600
}
This user can access pages tagged with either "pro-users" or "beta-testers" groups.
When to use group-based access:
- Paid features that free users shouldn't see
- Beta documentation for early adopters
- Partner-specific integrations
- Customer-specific content based on their plan or use case
This approach lets me maintain one documentation site while serving completely different content to different customer segments.
Tabs for Different Audiences
The simplest way to serve multiple audiences on the same page is tabs.
Mintlify's tab component lets you present alternative content side-by-side, letting readers choose what's relevant to them.
Example: Different code languages
<Tabs>
<Tab title="Python">
```
python
import requests
response = requests.get("https://api.example.com/data")
print(response.json())
```
</Tab>
<Tab title="JavaScript">
```
javascript
fetch("https://api.example.com/data")
.then(response => response.json())
.then(data => console.log(data));
```
</Tab>
<Tab title="cURL">
```
bash
curl https://api.example.com/data
```
</Tab>
</Tabs>
When to use tabs:
- Content that's parallel (same topic, different approaches)
- Users typically only need one option
- All options should be equally visible/accessible
When NOT to use tabs:
- Content that most users need to read entirely
- Options that build on each other
- More than 4-5 alternatives (gets unwieldy)
Conditional Navigation Paths
Not all customers need to see all sections of your documentation.
Mintlify lets you organize navigation in docs.json to create logical groupings. Combined with authentication and groups, you can show different navigation to different users.
Example: Organized navigation
{
"navigation": {
"groups": [
{
"group": "Getting Started",
"public": true,
"pages": [
"quickstart",
"installation",
"first-api-call"
]
},
{
"group": "Core Features",
"pages": [
"feature-overview",
"basic-usage",
"best-practices"
]
},
{
"group": "Advanced",
"pages": [
"custom-integrations",
"api-reference",
"troubleshooting"
]
}
]
}
}
The key insight: You don't always need to hide content. Sometimes, clear organization is enough.
Users will naturally gravitate to the sections relevant to them. The content is available to everyone, but the navigation makes it easy to find what's relevant.
Public vs. Protected Content
Sometimes you want most of your docs behind authentication, but certain pages public.
Mintlify makes this straightforward with the public property.
Make a single page public:
---
title: "API Overview"
public: true
---
Make an entire section public:
{
"navigation": {
"groups": [
{
"group": "Public Docs",
"public": true,
"pages": [
"overview",
"quickstart",
"pricing"
]
},
{
"group": "Protected Docs",
"pages": [
"api-reference",
"advanced-guides",
"internal-tools"
]
}
]
}
}
My approach:
- Public: Overview, quickstart, basic concepts (helps with SEO and sales)
- Protected: Detailed API reference, advanced guides, customer-specific content
This gives potential customers enough to evaluate the product while keeping detailed documentation for actual users.
How It All Fits Together
Here's how I think about the hierarchy:
┌─────────────────────────────────────────────┐
│ All Documentation │
├─────────────────────────────────────────────┤
│ Public Pages │
│ (Anyone can access) │
│ - Overview, quickstart, basic concepts │
├─────────────────────────────────────────────┤
│ Authenticated Pages │
│ (Logged-in users) │
│ - Full API reference, guides, tutorials │
├─────────────────────────────────────────────┤
│ Group-Restricted Pages │
│ (Specific user groups) │
│ - Pro users: advanced features │
│ - Beta: upcoming features │
│ - Partners: integration guides │
└─────────────────────────────────────────────┘
Within each level, I use tabs and clear navigation to help users find what's relevant without hiding content unnecessarily.
Lessons Learned
1. Start with organization, not restriction
Before adding authentication or group controls, ask: "Can I solve this with better organization?"
Clear sections and good navigation often eliminate the need for access control. Users self-select into the content they need.
2. Tabs are your friend
Any time you're tempted to create parallel pages (Python vs. JavaScript, beginner vs. advanced), consider tabs first. They keep related content together and reduce maintenance burden.
3. Don't over-segment
It's tempting to create hyper-specific documentation for every customer segment. Resist this urge.
Every segment you create is content you have to maintain. Start broad and only segment when you have clear evidence that users need it.
4. Test with real users
The best way to know if your documentation structure works? Watch someone use it.
Do customers find the content they need? Do new users complete the quickstart? Where do people get stuck?
User testing reveals gaps that internal review never will.
The Result
With this approach, I maintain a single Mintlify documentation site that serves:
- New users exploring the product (public quickstart)
- Active customers building integrations (authenticated API reference)
- Specific customer segments with unique requirements (group-restricted docs)
- Beta testers trying new features (group-restricted beta docs)
No duplicate content. No multiple sites to maintain. One source of truth with flexible presentation.
Resources
How do you handle customer-specific documentation? I'd love to hear what approaches have worked for you.
Top comments (0)