Know Your Audience

Every writing decision — what to include, which words to use, how deep to go — depends on who will read the text. Define your reader first.

Why it matters

The same feature needs different documentation for an administrator setting it up, an end user using it once a week, and a developer integrating it. Writing for "everyone" usually means writing for no one: beginners get lost and experts skim past padding.

How to define your audience

1. Name the reader. Write one sentence: "This topic is for [role] who wants to [goal]."

2. Decide what they already know. List the terms and concepts you can assume, and define everything else on first use.

3. Find the reader's goal, not the feature. Readers come to finish a task ("export a report"), not to learn a screen ("the Reports tab").

4. Check the context. Are they in a hurry, on a phone, mid-task, troubleshooting an error? Context shapes length and format.

Try it: who is this written for?

Read each sentence, decide who the reader is, then open the answer.

"Configure the SAML 2.0 IdP metadata URL and map the NameID attribute."

✅ An experienced administrator familiar with single sign-on. For a general audience, you'd need to explain SSO and each term — or link to a concept topic.

"Tap the blue button at the bottom of the screen to save your photo."

✅ A non-technical mobile user. It describes what they see and uses everyday words.

"Call GET /v1/orders with a bearer token; results are paginated with cursor."

✅ A developer. Concise, precise, and assumes knowledge of HTTP and authentication.

Checklist before you write

I can describe my reader in one sentence. I know what the reader wants to achieve with this topic. I listed the terms I can assume and the ones I must define. I chose the format that fits the reader's situation.

➡ Next: Write in plain language