Skip to main content
Before you design navigation or decide how to organize content, you need to answer one question: who is this for? 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 structured around the product rather than what people are trying to accomplish.

​
Why audience clarity comes first

Your audience shapes your structure. The same information needs a different organization depending on who’s reading and what they want 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. A single structure can’t put all three first, so you have to decide who comes first.

​
Define your primary reader

For each section of your documentation, define one primary reader: a person with a specific goal and a specific level of prior knowledge, not a demographic. 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 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 use AI tools to write or maintain documentation, a clear audience definition matters even more. Without one, AI tools write for a vague, generic reader who doesn’t represent anyone. Make your reader definition part of the context your AI tools receive every time they touch your docs. Where it goes depends on the tool:
  • Mintlify’s agent (in Slack, automations, and the API) reads .mintlify/AGENTS.md in your docs repository. It doesn’t read CLAUDE.md, Cursor rules, or other instruction files.
  • The editor’s agent reads the AI instructions in your editor settings. Each teammate sets their own.
  • Local tools like Claude Code or Cursor read their own instruction files. Copy the same definition into them so every tool writes for the same reader.
A minimal version looks like this:
.mintlify/AGENTS.md
Keep AGENTS.md inside the .mintlify/ directory. If you put it at the root of your project, Mintlify publishes it at /agents.md where anyone can read it.

​
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. Name the role, the goal, and the level of prior knowledge you can assume. Add it to .mintlify/AGENTS.md and your editor AI instructions. Your AI tools will write for that reader, and you’ll have something concrete to check drafts against. 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.