mintlify__docs/guides/understand-your-audience.mdx

---
title: "How to understand your documentation audience"
sidebarTitle: "Understand your audience"
description: "Define your documentation audience, research their goals and knowledge level, and apply those insights to write content that helps them succeed."
keywords: ["documentation audience", "user research", "audience personas", "technical writing audience", "user feedback"]
---

Documentation written for everyone is often useful to no one. The clearest, most accurate content still fails if it assumes the wrong level of knowledge, uses unfamiliar terminology, or addresses goals the reader doesn't have.

Understanding your audience is the foundation of effective documentation. This guide covers how to define who you're writing for, how to learn about them through research, and how to apply those insights to your content.

## Define your primary audience

Write every page for one specific type of reader. When you try to serve multiple audiences in the same content, you end up making compromises—adding beginner context that bores experts, or assuming knowledge that loses beginners.

Common documentation audiences include:

- **New users** learning the product for the first time, who need orientation, context, and step-by-step guidance
- **Developers integrating your API**, who need technical accuracy, code examples, and reference material—not general explanation
- **Admins configuring the product**, who need specifics on settings, permissions, and edge cases
- **Technical decision makers evaluating the product**, who need architecture overviews, security information, and capability summaries

Before writing any page, ask: who is reading this, and what are they trying to accomplish? Those two questions shape every decision that follows—structure, depth, tone, terminology, and what to leave out.

## Research your users

Don't rely on assumptions about your audience. Internal teams have too much context about their own product to be reliable proxies for users.

### Talk directly to users

User interviews surface insights that analytics can't. Ask users:

- How do they describe what your product does in their own words?
- What were they trying to accomplish the last time they consulted the documentation?
- What did they find confusing or missing?
- What terms do they use for the things your product does?

That last question is particularly valuable for documentation. If users call your feature a "webhook" and you're calling it an "event callback" in your docs, users searching for help won't find your content—and won't recognize it as relevant when they do.

### Embed with your support team

Support teams see documentation failures constantly. Ask them:

- What topics generate the most tickets?
- Where do users most often get confused or stuck?
- What do users say they expected to find but couldn't?

This is often the fastest way to find the highest-impact documentation gaps.

### Use feedback mechanisms

Give readers a way to signal when something isn't working. Thumbs up/down ratings and open-ended comment fields on documentation pages reveal which content is landing and which isn't. Negative feedback on a high-traffic page is a high-priority fix. See [Improve your docs](/guides/improving-docs) for more on using feedback data.

### Observe real navigation behavior

Session replay tools like [FullStory](https://www.fullstory.com) and [Hotjar](https://www.hotjar.com) show exactly how users navigate your docs. Where they pause, where they scroll back up, and where they abandon sessions reveals gaps that users often won't report directly.

## Apply what you learn

### Write to the right knowledge level

Calibrate your explanations to what your audience already knows—not what your team knows.

A developer integrating your API doesn't need you to explain what an API is. A non-technical admin configuring your enterprise product might. Define technical terms when introducing them for the first time, and link to deeper explanations rather than interrupting every page with foundational context.

```mdx
<!-- Define in context for less technical audiences -->
Your API key—a unique token that identifies your account—must be included in every request.

<!-- Skip basics for developer audiences -->
Include your API key in the Authorization header of every request.
```

### Match terminology to your audience's vocabulary

Use the words your users use. If your users call something a "project" and your product calls it a "workspace," your documentation feels foreign to people who haven't internalized your internal vocabulary. Document things with the terms users search for, then introduce your product's terminology alongside it.

### Adjust depth and structure to the task

Audiences at different stages have different needs:

- New users need orientation and reassurance—clear milestones, limited choices, and frequent confirmation they're on track
- Experienced users need to scan quickly—consistent structure, dense information, minimal context
- Reference documentation readers need completeness above all else

## Build audience awareness into your process

Understanding your audience isn't a one-time exercise. Products change, audiences evolve, and new user segments emerge.

A few practices that keep audience understanding current:

- **Review new pages with a support team member** before publishing. They'll quickly identify where assumptions are likely to break down.
- **Include audience assumptions in your writing brief.** Stating "this page is for developers who have already completed authentication" keeps the writing focused during review.
- **Use new hires as proxies.** Before they internalize your product's internal vocabulary, ask them to complete a task using only the docs. Their experience often mirrors that of new users.

## Frequently asked questions

<AccordionGroup>
<Accordion title="What if my documentation serves multiple audiences?">
Identify the primary audience for each page rather than trying to serve everyone in the same content. For products with genuinely distinct audiences—separate personas with different goals and knowledge levels—consider whether separate documentation sections or navigation paths make sense. Mintlify supports tab-based navigation that can separate content by audience without requiring entirely separate documentation sites.
</Accordion>

<Accordion title="How do I document for both technical and non-technical users?">
Create separate content for each rather than trying to blend them. A concept explanation for a non-technical decision maker and an API reference for a developer integrating your product serve different purposes and should be different pages. Where overlap is unavoidable, lean toward the more technical version and link out to lighter conceptual content for readers who need it.
</Accordion>

<Accordion title="How often should I revisit my audience assumptions?">
When you ship a major product change, when your user base shifts significantly, or when support ticket patterns change in ways that don't match your existing docs. Quarterly reviews of search analytics and feedback data help catch drift. More frequent check-ins with your support team can catch it faster.
</Accordion>

<Accordion title="What's the fastest way to identify documentation gaps?">
Ask your support team what topics they address most often that aren't covered well in the docs. This surfaces high-impact gaps faster than any analytics tool. User interviews, search analytics showing queries with no results, and session replays showing users scanning pages without finding answers all add more depth from there.
</Accordion>
</AccordionGroup>