Mastering Audience Analysis
The Writers' Table 1B
This is article 1B of The Writers’ Table. New here? Start with 1A: What Technical Writers Actually Do.
Ask a technical writer who their audience is, and most will say something like “developers” or “end users” or “IT administrators.” That’s not an audience. That’s a category. Writing for a category produces documents that work for nobody.
The audience analysis problem isn’t that writers don’t know they should think about the reader. It’s that they stop too early. “Developers” feels specific enough. It isn’t. A developer who wrote the code is not the same reader as a developer integrating your API for the first time. A developer at a startup with full access to the codebase is not the same as a developer at an enterprise with no access to any system except their own.
Your document will be read by a specific person in a specific situation with specific constraints. The job is to figure out who that person is before you write the first sentence.
Why “General Audience” Produces Nothing
When documentation is written for everyone, it ends up calibrated for the median — which, in practice, means calibrated for no one’s actual situation. It’s too basic for experts who need precision, too technical for newcomers who need context, and too vague for anyone who needs to make a decision.
The general-audience instinct comes from a reasonable place: writers don’t want to exclude anyone. But vagueness doesn’t produce inclusion. Structure does. Design your documents so that different readers can navigate to what they need without wading through what they don’t.
Start with knowing who your primary reader is.
Building a User Persona
A user persona for documentation purposes needs to answer these questions:
What do they already know? This is the hardest question because the answer varies. A useful proxy: what does your reader know the day before they open this document? They’ve been hired for a role; they’ve used the product for some period; they’ve read or not read the onboarding material. Specify that baseline.
What are they trying to do? Not in general — right now, at this moment, with this document in front of them. Are they stuck on a specific step? Are they evaluating whether to use this feature? Are they troubleshooting a failure? The task shapes the document.
What can go wrong? This is the question most personas skip. Your reader has failure modes: they’ll misread a term, skip a prerequisite, try the wrong approach first. Build a persona that includes the likely mistakes, not just the intended path.
What do they have access to? System access, time, patience, other documentation, and colleagues who can answer questions. A reader with a 20-minute window before a deployment and no one to ask is a different reader from someone doing exploratory learning on a Friday afternoon.
Creating the Persona: A Starting Process
You don’t need a research budget or a UX team. You need an hour and the evidence you already have.
Step 1: Pull the evidence. Support tickets from the last quarter. Onboarding survey responses. Search queries against your doc site. The questions your SME answers over and over in Slack. Any one of these beats guessing. Thirty minutes of reading tickets will tell you more about your reader than a week of speculation.
Step 2: Draft answers to the four questions. Three or four sentences total. Write what the evidence supports, not what the marketing persona claims. If you can’t answer one of the questions, that’s a finding that tells you what to ask about next.
Step 3: Check it with someone who talks to readers. A support lead, a sales engineer, a trainer. Ten minutes. You’re not asking them to approve it; you’re asking what you got wrong. They’ll know.
Step 4: Name it and attach it. “First-time API integrator” is a persona. “Developer” is not. Note which documents the persona applies to — one persona rarely covers your whole doc set.
Step 5: Revisit when the evidence changes. A new release, a new customer segment, a spike in a ticket category. Personas built once and filed away drift into fiction.
That’s the whole process. The books in Further Reading go deeper into research methods — Hackos and Redish in particular — but this gets you a working persona this afternoon.
The Expert Beginner Problem
The hardest reader to write for isn’t the complete novice or the deep expert. It’s the expert beginner — someone with substantial experience in an adjacent field who assumes their existing knowledge transfers.
A senior developer learning your API knows a lot about APIs. That knowledge is an asset and a liability. They’ll skip the context that would help them and dive into the reference, where they’ll confidently make wrong assumptions based on how other APIs behave.
Documents for expert beginners need to be specific about where your product diverges from the pattern. Not “here’s how authentication works” but “here’s how our authentication differs from OAuth 2.0 in two specific ways.” The expert doesn’t need the full explanation. They need the delta.
Adjusting Depth in Practice
Once you have a real persona, document calibration becomes mechanical. Take any section you’ve written and ask: given who this reader is, does this sentence tell them something they don’t know and need to know? If the answer is no, cut it or move it to a separate document aimed at a different reader.
The test isn’t “is this information accurate?” Accurate information that a reader already knows wastes their time and teaches them that your docs aren’t worth reading carefully. Every sentence should be earning its place against a specific reader’s knowledge gap.
Further Reading
About Face: The Essentials of Interaction Design — Alan Cooper, Robert Reimann, David Cronin
User and Task Analysis for Interface Design — JoAnn T. Hackos, Janice C. Redish
“Personas Make Users Memorable” — NN/g — https://www.nngroup.com/articles/persona/
What you can do
Pick a document you’ve written or read recently. In three or four sentences, describe the primary user: what they know going in, what they’re trying to accomplish, and the most likely thing they’ll get wrong. What have you learned? What changes would you make?
In the next article, we’ll look at how readers interact with your documents.
I’ve included a link to a workbook, Personas-workbook.xlsx, that I’ve used in my work. Use it to start, organize, and modify it for your needs to create and record personas. It’s not comprehensive. You’ll need to edit it for your own documentation work. But I think it’s a good start.
Next Monday: Writing for the F-Pattern — how readers actually process text on screens, and how to structure documents around the way people scan rather than read.