Writing for your reader
Find out who you're writing for, then write so they get it right on the first read.
2 min read
Clear documentation starts before the first sentence. It starts with knowing who will read it, what they're trying to do, and what they already know.
Start with the reader#
Before writing any page, answer three questions:
- Who is reading? An administrator setting things up? An end user in a hurry? A developer integrating an API?
- What are they trying to do? Name the task in a few words.
- What do they already know? Assume less than you think. Define terms the first time you use them.
The first-read test#
Good documentation passes one test: the reader gets it right on the first read, without asking anyone. To check, hand a draft to someone who hasn't seen the product and watch where they hesitate.
| Where they hesitate | What it usually means |
|---|---|
| Re-reading a sentence | The sentence is too long or uses unfamiliar words |
| Asking "where do I find that?" | A step is missing or the interface name is wrong |
| Skipping ahead | The page opens with background instead of the task |
| Stopping to search | The heading doesn't match how the reader thinks about the task |
Cut the jargon#
Engineers use precise terms. Readers often don't share them. Replace internal vocabulary with the words your users use, and when a technical term is unavoidable, explain it once in plain language.
| Instead of | Write |
|---|---|
| Instantiate the credentials in the administrative console | Create an API key in Settings > API |
| The operation is idempotent | You can safely repeat this request. It won't create duplicates |
| Authenticate against the endpoint | Send your API key with each request |
Write steps people can follow#
- One action per step
- Name the exact button or field, in bold
- Say what the reader should see afterwards
- Put warnings before the step they apply to, not after
Check your writing with the Readability Lab.
Was this page helpful?