Skip to main content
Before you design navigation or decide how to organize content, you need to answer one question: who is this for? That sounds obvious. Most teams think they know their audience. But “developers” isn’t specific enough. Neither is “our users.” When your audience is everyone, your docs end up written for no one — structured around the product rather than around what people are trying to accomplish.

​
Why audience clarity comes first

Structure is downstream of audience. The same information needs to be organized differently depending on who’s reading it and what they’re trying to do. A developer integrating your API for the first time needs a path that starts with authentication and gets to a working example as fast as possible. A developer returning to look up a specific parameter needs something they can scan in five seconds. A technical lead evaluating your product needs to understand the architecture before they care about implementation details. These are three different readers with three different needs. If you try to serve all of them equally with the same structure, you’ll serve none of them well.

​
Define your primary reader

For each section of your documentation, define one primary reader. Not a demographic — a person with a specific goal and a specific level of prior knowledge. A useful reader definition answers three questions:
  • Who are they? Their role, experience level, and relationship to your product.
  • What are they trying to do? The specific task or goal that brought them to the docs.
  • What do they already know? What you can assume, and where you’ll need to fill gaps.
A good reader definition is concrete enough to write for. Backend engineers evaluating your API is not. A backend engineer who signed up yesterday and needs to make their first authenticated API call is.

​
Use your audience as AI context

If you’re using AI tools to help write or maintain documentation, audience definition isn’t just useful — it’s load-bearing. AI tools write generically by default. Without explicit context about who the reader is, they’ll produce content pitched at an undefined middle ground that doesn’t serve anyone particularly well. The solution is to make your reader definition part of the context your AI tools receive every time they touch your docs. In Mintlify, the most practical way to do this is with a CLAUDE.md file or a Cursor rules file in your docs repository. These files are read by AI coding assistants before they make any changes, which means your audience definition travels with your docs and shapes every AI-assisted edit. A minimal version looks like this:
.claude/CLAUDE.md
## Audience

Our primary readers are backend developers integrating a B2B API for the first time.
They are comfortable with REST and JSON but may not have used our product before.
They want working examples, not explanations of concepts they already understand.

Write for this reader unless a page explicitly specifies otherwise.
This context shapes everything — word choice, depth of explanation, the kinds of examples the AI reaches for.

​
Use Mintlify’s assistant as a feedback loop

Once your docs are live, Mintlify’s AI assistant gives you a continuous signal about whether your documentation is working. The questions users ask the assistant — and the ones it can’t answer well — tell you where your content is missing, pitched at the wrong level, or structured in a way that makes it hard to find. Review assistant conversations regularly, especially for your highest-traffic pages. If users are asking questions that should be answered by content that already exists, the problem is usually structural: the information is there, but readers can’t find it or recognize it as relevant to their goal.

​
A practical starting point

Before moving to the next lesson, write a one-paragraph reader definition for the section of your docs you’re most responsible for. Be specific: name the role, the goal, and the level of prior knowledge you can assume. Add it to a CLAUDE.md file in your Mintlify repository. Your AI tools will use it. So will you. Next up: Choose the right content type — how to categorize each page before you write it, and why mixing content types is one of the most common reasons docs become hard to navigate.