How to understand your documentation audience

Documentation written for everyone tends to help no one. A page can be accurate and clearly written and still fail, because it assumes knowledge the reader lacks, uses words they do not use, or answers a question they never asked.

Knowing your reader comes before everything else in documentation. Decide who you are writing for, find out what they actually know and want, and let that shape the page.

Define the primary reader

Write each page for one kind of reader. A page that tries to serve several audiences at once ends up compromising: beginner context that bores experts, or assumed knowledge that strands beginners.

Most documentation serves some mix of these readers:

• New users meeting the product for the first time. They need orientation, context and step-by-step guidance.
• Developers integrating an API. They need precision, code examples and reference, not general explanation.
• Administrators configuring the product. They need the exact settings, the permissions involved and the edge cases.
• Technical decision makers evaluating the product. They need architecture overviews, security details and a clear account of what it can and cannot do.

Before you write a page, answer two questions: who is reading this, and what are they trying to get done? Those answers decide the structure, the depth, the tone, the terminology and — often most important — what to leave out.

Research your readers

Do not work from assumptions. The people who build a product know too much about it to stand in for the people who use it.

Talk to them

Interviews surface things no metric will. Ask readers:

• How would you describe what the product does, in your own words?
• What were you trying to do the last time you opened the documentation?
• What was confusing, or missing?
• What do you call the things the product does?

The last question matters most for documentation. If your readers say “webhook” and your pages say “event callback”, a reader searching for help will not find the page — and will not recognize it as relevant when they land on it.

Sit with support

Support teams watch documentation fail every day. Ask them:

• Which topics generate the most tickets?
• Where do people get stuck or confused?
• What did people expect to find in the docs and could not?

This is usually the fastest route to the gaps that matter most.

Collect feedback on the pages themselves

Give readers a way to tell you a page did not work. A negative signal on a heavily used page is a high-priority fix.

Reed’s footer shows a static “Was this page helpful?” prompt on every page, but it submits and stores nothing, so this channel is yours to set up. The simplest version is a sentence at the end of key pages pointing to wherever you already take reports — an issue tracker, a support address, a community forum. When your docs live in a public Git repository, an issue or a pull request against the page is a natural way for technical readers to flag a problem.

Watch where readers go

Traffic data shows which pages people reach and which they leave quickly. Reed can emit one of six analytics providers — GA4, Plausible, PostHog, Fathom, Umami and Matomo — configured by value in docs.json. See Analytics.

Session-replay tools, which record where readers pause, scroll back and give up, are a different matter. Reed does not let configuration inject arbitrary scripts, so a replay tool that is not one of the supported providers cannot be added to a Reed site today. If you need that level of observation, run moderated sessions instead: give someone a task, watch them attempt it with only the docs, and take notes.

Apply what you learn

Write to the reader’s level

Calibrate explanations to what your readers already know, not to what your team knows.

A developer integrating your API does not need an API explained. An administrator configuring an enterprise product might. Define a technical term where it first appears, and link to a deeper explanation instead of stopping every page to teach fundamentals.

mdx

Your API key — a unique token that identifies your account — goes in every request.

Send your API key in the Authorization header of every request.

The first line suits a less technical reader. The second suits a developer, who would find the definition in the first one slow.

Use the reader’s words

If your readers say “project” and your product says “workspace”, every page sounds foreign to anyone who has not absorbed your internal vocabulary. Lead with the term readers search for, then introduce the product’s term alongside it.

The same words matter outside the page body. Frontmatter title and description are what a search result shows, and the description is also the line that describes the page in llms.txt. Write both in the reader’s vocabulary. See llms.txt and markdown mirrors.

Fit depth and structure to the reader’s stage

Readers at different stages need different pages:

• New users need orientation and reassurance: clear milestones, few choices, frequent confirmation that they are on track.
• Experienced users need to scan: consistent structure, dense information, minimal preamble.
• Reference readers need completeness above everything else.

Documentation content types turns these stages into four kinds of page.

Keep it current

Knowing your readers is not a one-time exercise. Products change, audiences shift, and new kinds of reader arrive.

A few habits keep your picture accurate:

• Have someone from support review new pages before they ship. They will spot the assumptions that are about to break.
• Write the audience into the brief. “This page is for developers who have already set up authentication” keeps the draft focused and gives reviewers something to check against.
• Use new hires as test readers. Before they learn the internal vocabulary, ask them to complete a task using only the docs. What trips them up will trip up new users too.

Frequently asked questions

What if the documentation serves several audiences?

Give each page one primary reader instead of writing every page for everyone. When the audiences are genuinely distinct, give them distinct paths through the site. In Reed, navigation is organized into tabs, each holding its own groups of pages, so a tab per audience is one way to separate them within a single site. See Navigation.

How do I write for technical and non-technical readers at once?

Mostly, you do not: write separate pages. A concept explanation for a decision maker and a reference for an integrating developer do different jobs. Where overlap is unavoidable, write the more technical version and link out to lighter conceptual material for readers who need it.

How often should I revisit my assumptions about readers?

Whenever you ship a major change, whenever your user base shifts noticeably, and whenever support tickets stop matching what the docs cover. A quarterly look at traffic and feedback catches slow drift. Regular conversations with support catch it sooner.

What is the fastest way to find documentation gaps?

Ask support which questions they answer most often that the docs do not cover well. That finds high-impact gaps faster than any dashboard. Interviews, traffic data and watching someone attempt a task with only the docs add depth from there.

Related pages

Documentation content types

Match each page to the reader’s need in the moment.

How to write technical documentation

Voice, tone and terminology.

Structure navigation

Give each audience a path through the site.

Improve your docs

Turn feedback and traffic into changes.