102. Know your reader

Imagine a designer preparing a proof for review. The export fails. She opens the help page and finds an account of the export system's architecture: accurate, considered and of no immediate use. Somewhere below it there may be a remedy. The page appears willing to keep that information to itself.

This is a fictional situation, but it gives us a practical editorial question. What must the reader know before she can take the next useful action?

Begin there. The answer will decide the title, the opening, the amount of explanation and whether a joke has any business in the paragraph. A reader is easier to write for when you can see what they are trying to do.

Find the question already in progress

Readers reach a page from somewhere: a failed operation, a search result, a link in a support reply, a comparison with another product. They bring a task and some prior knowledge. Your introduction arrives halfway through that situation.

Collect the words people actually use. Support tickets show where the product or its documentation failed to answer a question. Search queries show what people call the thing they need. Sales conversations show which uncertainty stands between interest and a decision. None is a complete portrait of the audience, but each can change a sentence.

Keep the observation separate from your interpretation. “The reader searched again after opening this page” is an observation. “The reader hated the page” is a story about their feelings. The first suggests a question to investigate. The second may make the research report more dramatic.

Turn evidence into a page decision. In this fictional research packet, several readers search for export folder, while the existing page is titled Output configuration.

Evidence	Question to investigate	Possible edit	Check
Readers search for export folder	Can they recognize the relevant page?	Name the export folder in the title; preserve the actual control name in the steps	Ask a reader to find the instructions from the search results
Readers ask where the file went	Does the procedure state the destination?	Add the destination and success check after export	Follow the task and locate the resulting file
Buyers ask whether a format is supported	Is the compatibility information visible?	Put the supported formats near the relevant claim	Ask a buyer to make that decision from the page

These are hypotheses to test. A decline in support tickets alone cannot establish that the edit worked; fewer people may have used the feature. Look at the task as well as the count.

Sketch the decision, then the person

A useful reader sketch identifies a goal, starting knowledge and next decision. Add circumstances only when they change the writing.

Thin sketch: A professional designer who values quality.

Useful sketch: A designer has exported a proof before, but this export failed. She needs to know whether a file was created and whether repeating the operation is safe.

The second sketch gives the page work to do. It does not need an invented age, breakfast or personality type. If the source evidence establishes time pressure, a small screen or a particular accessibility need, include it. Otherwise keep the uncertainty visible.

You can record an observed feeling or a concern the person expressed. Do not fill a mandatory “emotion” field with a guess. A failed operation deserves clear recovery guidance whether the reader is angry, calm or already making tea.

Write the page's promise in your working notes:

This page helps a reader diagnose a failed proof export, identify any partial output and choose a supported next action.

Add its boundary:

Detailed export settings and API integration belong on linked pages.

The boundary keeps the draft from expanding to serve every possible visitor. Route other readers to the relevant page. Do not make them discover the mismatch after following half a procedure.

Notice what expertise has hidden

Once you know a workflow, its missing steps become hard to see. You remember where the control lives. You know which file is editable. You know that the example assumes a saved document. The draft may contain none of this.

Perform the task from the declared starting state and keep a short record of surprises: an unavailable control, a wait, a dialog you forgot, an output name that differs from the input. These details identify the places where prose may need to work.

Watching a reader try the task can expose a different gap. Give them the page and a concrete assignment, then let them proceed without coaching. Record where they pause, what they inspect and what they do next. If they ask for help, note the point before answering.

Do not conclude that every stumble needs another paragraph. The label may be misleading. The interface may hide the control. The procedure may be correct for a different version. Writing can explain a genuine constraint; it should not excuse a defect that needs a product change.

A precise observed detail carries more information than a general verdict. “The reader looked for an export folder in the document settings” gives an editor something to investigate. “The experience was unintuitive” gives everyone something to agree with.

Choose the distance from the action

A blocked reader needs an answer close to the event. A learner has room for a model. A buyer needs a criterion. The same person can occupy all three positions in an afternoon.

Reader's present task	Useful opening	Detail to keep close
Recover from failure	The visible symptom and scope	Supported diagnosis, state of the work and next action
Learn a concept	A definition or observable puzzle	Mechanism, example and limit
Choose an option	The distinction that changes the choice	Compatibility, cost or other relevant conditions
Repeat a familiar task	The short route	Exact labels, prerequisites and result

These are starting points, not compulsory templates. An unknown cause stays unknown in every row. A learner may need a warning before an attractive explanation.

For the following fictional example, the application reports that the selected destination is read-only. The source packet confirms that no proof file was created. In this example, choosing a writable folder and exporting again produces the proof.

For the blocked reader

The destination folder is read-only. No proof file was created. Choose a writable folder and export again.

For the learner

The destination folder is where the application writes the proof. A read-only folder can contain files you can inspect, but the application cannot add the new proof there. Choose a folder that permits writing.

The first version supplies the immediate facts and action. The second develops the distinction between reading and writing. Neither needs a story about how the reader feels.

Now remove the confirmed cause from the packet. The first version must change. “Export did not finish” remains supportable; “the destination folder is read-only” does not. Knowing the reader's need gives you a reason to investigate the cause, not permission to supply one.

Make the page easy to enter

A search result can place someone in the middle of a manual. Give the page enough local context to stand on its own: the relevant product, task and version boundary, when those affect interpretation.

Write descriptive headings. Someone scanning visually or navigating with a screen reader should be able to identify the section they need. A clever heading can work in an essay; a recovery page needs the words people are looking for.

Test several paths through the same page. Read the title and opening alone. Then read only the headings. Then follow only the instructions and required notices. Each route should provide what its reader needs without assuming the other routes were taken.

Detail can be layered. Put the short answer near the start, develop the explanation below it and link to related material where a new question arises. Keep a required fact on the current page. A warning linked from the final step arrives too late.

The reader who chooses to stay deserves more than a sequence of signposts. Explain why the action works, where the model stops applying or what distinguishes a similar-looking state. Scanning gets someone to the passage; substance makes the visit worthwhile.

Keep the language open to international readers

Use familiar words for the relationships around technical terms. Preserve the term itself when it is needed, and explain it at the point where a newcomer must use it.

Retain articles, relative pronouns and repeated prepositions when they clarify the sentence. Compare these invented sentences:

Compressed: Check files the application created before closing.

Explicit: Before you close the application, check the files that it created.

The revision establishes what happens before closing and what is being closed. It is slightly longer because it now does the whole job.

Keep essential instructions literal. “Choose a writable folder” survives more contexts than “find the proof a new home.” The latter may be a harmless image in an explanation, but the reader should never have to translate an image into an executable step.

An international audience does not require lifeless prose. A visible object, a well-chosen verb and an unexpected consequence can travel without a local idiom. Explain unfamiliar cultural references when they are necessary; usually a more relevant example is available.

Do not assume a city tells you what someone knows or how they read English. Test with the intended audience. Machine translation can expose awkward syntax, but a readable translation is not evidence that the original instructions are correct.

Let observation supply the voice

Reader research offers more than topics. It gives prose a point of view.

Consider this fictional note from a proof review: the designer opens one file, returns to the folder, opens another and repeats the sequence to compare a small difference. An abstract draft might say that comparison involves workflow friction. An attentive draft can show the repeated action.

She opens the second proof to check the join, then returns to the first to remember what she saw. The comparison is taking place partly on screen and partly in memory.

The passage selects a relevant detail and lets its consequence emerge. It does not need to declare the process maddening or promise that a particular product will cure it. In a genuine case study, the actions and interpretation would need support; here they are explicitly invented for the exercise.

Use a small scene when it helps the reader recognize a problem or understand a mechanism. Begin at the consequential action, include the detail that makes the situation legible and move into the explanation. Cut the scene if it delays recovery or repeats what the reader already knows.

The tone can be dry without being cold. Let the troublesome arrangement bear the joke. A reader looking in the wrong place is evidence about the task, not comic material about the reader.

Turn the page into a route

A task page usually needs some combination of orientation, choice, action, confirmation and recovery. Check which parts this task requires rather than forcing every page into the full sequence.

A short reference entry may only identify an element and its contract. A tutorial may guide a longer sequence. An overview may do its best work by helping the reader choose a destination.

For a fictional review application with three sections, an overview could say:

Open Proofs to inspect drawings, Comments to read the review and Settings to choose where exported files are saved.

That is enough if the page's job is routing. A description of the application's “integrated review environment” would leave the same choice unresolved.

Show a final success condition when the task has an observable result. If an operation can partially succeed, say how the reader distinguishes partial output from completion. Do not end the procedure at the click merely because the click was easy to describe.

Test with a reader who needs the page

Give a representative reader a task that matches the page's promise. Define the observable result before the test. For the fictional read-only-folder case, success would include identifying the reported cause, choosing a writable destination and finding the resulting proof.

Observe whether the person can find the page, understand its relevant conditions, perform the action and verify the result. Ask afterward what they expected, where they hesitated and what they did when uncertain.

“Was it clear?” tends to invite a polite answer. A wrong action, an unrecognized label or an unexplained pause gives you a better starting point.

If no representative reader is available, perform a bounded self-review. Enter through search, read the heading trail and follow the task from a clean state. Record that this is an editorial check, not a user test. Experience with the product still affects what you notice.

For a decision page, ask someone to decide using the page's actual facts. For a concept page, ask them to explain the distinction or choose an example. The test should follow the page's job.

Keep the evidence useful after publication

Record why important editorial choices were made. A short private note can name the question, the evidence, the documented version, the test performed and the event that should trigger review.

Preserve the reader's wording when it affects discoverability. Preserve the exact control name where it locates the action. The two can coexist: a task heading can use the familiar phrase and the instructions can introduce the product's label.

Revisit the page after a relevant product change, new support pattern or translation finding. Treat a change in traffic as a signal to investigate, not a diagnosis. Record what changed in the page and why.

The person maintaining the article should be able to tell which detail was observed, which behavior was tested and which question remains open. That makes the next revision easier to begin and harder to invent.

Practice: one reader, three openings

Use the read-only-folder fact packet above. Write an opening for a blocked reader, a learner and a returning user. Keep the facts fixed while changing their order and depth.

Then review each version:

1. Identify the question the first sentence answers.
2. Underline every claim and match it to the packet.
3. Check that the reader can locate the next action.
4. Read aloud and remove a flourish if it delays the answer.
5. Add useful context only where its absence would leave a gap.

For the learner, try a developed sentence followed by a short consequence. For the blocked reader, try the plainest complete answer. Judge each by its job rather than choosing a favorite sentence and installing it everywhere.

Repeat the exercise with the cause removed from the packet. This time the application reports only that export did not finish. Keep that uncertainty in every register. If the expressive version quietly restores the missing cause or promises a safe retry, the second pass has found a factual defect.

Checklist

• The page has a defined reader task, starting knowledge and boundary.
• Reader observations are distinct from assumed motives or emotions.
• Research has produced a concrete heading, sentence, link, warning or structural choice.
• The opening suits the reader's present task.
• Necessary terms and conditions appear before the reader must use them.
• Headings, instructions and required notices support separate entry paths.
• Examples are sourced or clearly fictional; causes and recovery remain within evidence.
• A relevant observed detail supplies interest without cultural obscurity or invented drama.
• The task, decision or explanation has been tested at the stated level.
• A private record preserves the basis for the next revision.