Understand your audience

The biggest wastes in docs writing come from false assumptions about the reader. "Our users are senior engineers" — actually half are JR engineers onboarding. "They'll read the quickstart first" — actually most land deep on a Google-indexed reference page. "They don't need the basics explained" — actually even experts appreciate concise recaps.

This guide covers how to find out who actually reads your docs, what they're trying to do, and how to ship content that matches.

Why persona research matters for docs

The audience — three groups now

Classically, docs audiences were:

1. Evaluators — deciding whether to adopt your product.

2. Implementers — building the first integration.

3. Operators — maintaining a running integration.

In 2026 add:

4. LLM agents — reading on behalf of human users to answer questions or generate code.

All four deserve tuned content. See writing for LLMs for the agent-specific story; this guide focuses on the three human groups.

Evaluators

Shape: senior-ish, time-constrained, comparing 2-3 alternatives. Wants to understand trade-offs + pricing + capabilities in 15 minutes.

Reads:

• Landing page (marketing site, not docs).

• "Introduction" / overview.

• "Concepts" / architecture.

• A couple of reference pages to check claims.

Almost never finishes a tutorial. Rarely reads past the third paragraph of any page.

Content tuning: first paragraph of every page answers "what is this for". Architecture page exists and shows the big picture. Pricing + tiering surfaced.

Implementers

Shape: mid-level, task-focused, usually on a deadline. Wants the first working integration ASAP.

Reads:

• Quickstart / tutorial.

• Authentication specifics.

• 2-3 core API endpoints relevant to their use case.

• Error code reference when something breaks.

Doesn't read architectural explanations unless they hit a design decision they disagree with.

Content tuning: working examples in every language they might use. Complete copy-paste snippets. Error codes documented by error message text (so Ctrl-F finds them).

Operators

Shape: senior, managing an already-working integration. Needs rate limits, webhooks, monitoring, migration docs.

Reads:

• Webhook reference.

• Rate limit docs.

• Changelog + migration guides for version bumps.

• Security / compliance docs.

Skips tutorials entirely.

Content tuning: Every breaking change documented with migration steps. Every quota numerically exact. Security posture explicit.

How to learn who your actual readers are

Analytics

NookDocs's analytics + on-site search logs are the cheapest signal:

• Top landing pages — where readers arrive. Reveals which content Google sends traffic to.

• Top search queries — what readers look for. Reveals gaps (queries returning 0 results) and winning terms.

• Session paths — what readers visit after landing. Reveals whether the "next step" you expected actually works.

• Bounce rate per page — high bounce on a reference page is usually fine; high bounce on a tutorial's step 2 signals that step is broken.

Support + forum questions

Every repeated question is a missing or hard-to-find docs page:

1. Dump 3 months of support tickets into a spreadsheet.

2. Tag each by topic (auth / webhooks / billing / deploy / …).

3. Sort by frequency.

4. For the top 20 topics, check: is there a docs page covering this? Is it findable via search? Is it the first result?

Usually the answers are: half the time no page exists, a third of the time the page exists but is unfindable, and the rest of the time the page exists but doesn't answer the question directly.

Forums + Stack Overflow

Search for your product name on Stack Overflow, Reddit, Hacker News. Read the top 50 questions.

Patterns to notice:

• Exact phrasing of queries — "how to X with Acme" gives you the precise SEO + GEO target phrases.

• Misconceptions — if the same misconception appears 5 times, your docs aren't clarifying it. Write a page that directly addresses it.

• Workarounds — if the community invented workarounds for a missing feature, that's a product gap to close + a docs gap to fill.

User interviews

Expensive but highest-signal. 5 interviews with recent implementers tells you more than 500 session replays.

Targeted questions:

• "Walk me through the first day you used Acme. What did you read?"

• "When you got stuck, what did you try? What worked, what didn't?"

• "Is there a piece of our docs you wish existed?"

• "Did you ever feel condescended to by the docs? Or felt like it assumed you knew something you didn't?"

Avoid asking users to rate their own skill level — self-assessment is unreliable. Infer skill level from the vocabulary they use.

LLM-assisted research

Paste your product name + common questions into ChatGPT / Claude / Perplexity. See what they answer.

Signals:

• Missing citations — the LLM answers correctly but doesn't cite your docs. Your docs aren't ranking for that query (see GEO).

• Wrong answers — the LLM makes up features you don't have, OR misses features you do. Your docs need clearer canonical pages.

• Outdated answers — LLM cites your 2022 blog post when the correct answer is in a 2025 docs page. Update old content and add redirects.

Building a persona

Once you have data, codify into 2-3 personas. Each persona gets a card:

# Persona: Mid-level Developer (Mia)

## Context
- 3-5 years of dev experience
- Shipping a side project or startup MVP
- Evaluating Acme vs Competitor X

## Goals
- Ship first integration in <1 hour
- Understand pricing before committing
- Find runnable code examples

## Pain points
- Abandoned Competitor X because docs assumed too much
- Doesn't have time to read 10k-word concept guides
- Gets frustrated when "See below" references scroll offscreen

## Vocabulary
- Says "JWT" not "JSON Web Token"
- Says "endpoint" not "route"
- Says "env var" not "environment variable"

## What she reads first
- Landing page
- Quickstart
- Auth doc (because every integration starts with auth)

## What she skips
- Architecture explanations
- Migration guides (not a current operator yet)
- Comparison pages

Typical team has:

• 2-3 primary personas — 80% of docs optimisation targets these.

• 1-2 edge personas — niche but important (security auditors, compliance officers).

Don't split further than that. Three personas × three voice variations × three example variations = nine versions of every page. You won't ship.

Persona-specific content tuning

Introduction paragraphs

First paragraph of every page should work for all primary personas. Usually means: answer the "what is this" in 1 sentence, signal who it's for in the next.

# Rate limits

Acme caps each API key at 100 requests per minute by default. Operators
tuning quotas, implementers debugging 429 errors, and architects
evaluating production readiness all land here. Enterprise plans scale
to 1000/min.

One sentence per likely reader. Implementer reads line 1 + 2 + stops. Architect reads line 2 + skips to the Enterprise mention. Operator reads the whole thing.

Examples

Every working example should be one that the dominant persona might actually ship. Generic foo/bar examples frustrate — readers have to translate back to their domain every time.

❌ Generic
const response = await fetch("/api/foo", { body: JSON.stringify({ bar: 123 }) });

✅ Plausible for an implementer reading this
const response = await stripe.paymentIntents.create({
  amount: 2000,
  currency: "usd",
  payment_method_types: ["card"],
});

Escape hatches for advanced readers

Beginners want step-by-step. Advanced readers want "just show me the config". Use callouts to provide both without bloating the main prose:

<Accordion title="Quick version (if you know DNS + CNAMEs)">
  Add `cname.nookdocs.site` as a CNAME target for your subdomain.
  SSL provisions automatically within 30 seconds of verification.
</Accordion>

## Step-by-step version

<Steps>
  <Step title="Open your DNS provider">
    ...
  </Step>
  ...
</Steps>

Advanced reader clicks the accordion, gets the TL;DR, moves on. Beginner reads the step-by-step. Both groups served, no duplication of conceptual content.

Common persona mistakes

Research cadence

Cheap signals weekly, expensive signals quarterly:

• Weekly (15 min): Scan top 20 search queries + top 5 bounce pages in analytics.

• Monthly (1 hr): Review last month's support tickets. Tag + count. Update docs for top 3 themes.

• Quarterly (1 day): 3-5 user interviews. Recalibrate persona cards if patterns shifted.

• Annually (1 week): Full IA audit through the current persona lens. Move pages, split sections, retire content.

Related

• Style and tone — voice tuning per persona

• Content types — different personas want different Diátaxis modes

• Writing for LLMs — the fourth persona + its content needs

• SEO for docs — Search Console queries are the cheapest persona signal

• Analytics — the on-platform data source