Review: Match the Document to the Reader's Job

By the end of this lesson, you will be able to...

• Diagnose why one overloaded documentation page fails several readers at once.

• Connect reader promise, document mode, explanatory order, clarity, evidence, and representation in one review.

• Propose a small rewrite plan that separates reader jobs without losing necessary links.

Idea in one sentence: A document becomes clearer when its shape follows the reader's immediate job, and a review makes every mismatch visible before polishing sentences.

Core Insight

Nia opens a page called Managing imports. She has an import that stopped with source_unreachable, and a customer is waiting for the file. The page begins with an introduction for new users, then gives a six-step first-import exercise, then explains why imports run in the background, then lists the POST /v1/imports fields, and finally hides one sentence about failed source URLs in a long troubleshooting section.

The page has useful material. It has the wrong shape for Nia's moment.

She is not studying the product for the first time. She is not asking why the architecture is asynchronous. She is trying to recover one failed import. The page makes her scroll through three other jobs before she can act.

This review gathers the first seven lessons into one test: can a reader find the next useful thing, understand why it matters, inspect the evidence or model, and act without receiving a promise the document cannot keep?

The Reader-Jobs Map

The same import system can need several documents. The topic does not decide the document type; the reader's job does.

The first four reader jobs came from lesson 002. Lesson 007 sharpened the reference case: a reader needs a valid request, response meaning, an error action, and edge cases close to their decision. A runbook is about to add a different pressure: an operator needs safe action under time pressure.

Plain meaning:

Do not ask one page to teach, explain, provide lookup, and direct urgent recovery in the same uninterrupted path.

In Nia's situation:

The error code belongs in a reference or recovery path. The first-import exercise can link to that path, but it should not stand between Nia and the next action.

Technical name:

This is mode mixing: one document tries to serve incompatible reader jobs without clear boundaries, handoffs, or entry points.

What You Can Now See

Use the six questions below to review a page. They combine the tools already learned in this track.

These questions are not a style score. They identify the smallest repair that changes the reader's path. A vague sentence may need a concrete noun. A page that mixes a tutorial and reference usually needs a boundary and links, not another adjective.

Worked Diagnosis: One Page, Three Failed Promises

Here is a shortened version of Nia's page:

Managing imports

Imports are asynchronous because our distributed worker architecture improves reliability. To create your first import, open the dashboard, create a CSV, and choose a source. The API uses POST /v1/imports. If you receive source_unreachable, check that the URL works. Imports may take several minutes.

At first glance, this is concise. It still asks four different readers to decode the same paragraph.

The naive repair is to add another paragraph under the same heading. That makes the page longer but keeps the collision. A better repair separates the promises:

Start here: complete your first import       -> tutorial
Create an import with the API                -> endpoint reference
Why imports are asynchronous                 -> explanation
An import cannot fetch its source file       -> troubleshooting / runbook

For the endpoint reference, write the error entry precisely:

422 source_unreachable: the import worker cannot fetch source_url. Provide a reachable https URL or a signed URL that the worker can use. Then retry the intended import according to the idempotency rule.

This is a worked repair, not merely a label change. It contains a visible signal, the component that sees the failure, a bounded action, and a link-worthy boundary. It also avoids claiming that a browser can test the worker's access exactly.

So far, the review has moved from an overloaded paragraph to four reader routes. The facts did not disappear; the reader no longer has to sort them while trying to act.

Check: A page gives a beginner a numbered first setup, then a table of every configuration field, then a two-page rationale for one default. Which repair is strongest?

Think first, then reveal.

Answer: Keep the first setup as a tutorial, move the exhaustive field table into reference, and link the rationale as explanation. The material may remain connected, but each route should make one clear promise.

Common Confusions

Confusion: One topic should live on one page

Why it is tempting:

One page feels complete and is easy for the writer to name.

Better model:

One topic can require several linked artifacts. Completeness for the writer is not the same as a usable path for the reader.

Confusion: Short means reference; long means tutorial

Why it is tempting:

Reference pages often look compact, and tutorials often contain steps.

Better model:

Mode follows the reader's need, not length. A long reference can still support lookup. A short tutorial can still create a learning experience. The difference is the promise and the reader's work.

Confusion: Splitting documents removes context

Why it is tempting:

Separate pages can send the reader away from useful background.

Better model:

Link context at the decision point. Splitting preserves focus when the handoff says why another page matters and what question it answers.

Check: A reference says, “For more information, see the import guide.” What is missing from this handoff?

Think first, then reveal.

Answer: Name the question the guide answers. For example: “To learn why an accepted import can still fail later, see How asynchronous imports progress.” A generic link makes the reader repeat the search.

Trade-offs and Limits

Separating reader routes improves findability and makes each promise easier to keep. The trade-off is navigation and maintenance: more artifacts need clear names, stable links, and owners. A split can also fail when it creates tiny pages that make a reader bounce between tabs for one action.

Keep material together when it serves the same immediate decision. Split it when a reader must switch from studying to doing, from lookup to explanation, or from ordinary use to incident recovery. You can see the boundary when a heading makes the reader ask, “Why am I reading this now?”

This review does not settle every information-architecture question. It gives a local test. Use reader evidence—search terms, support questions, failed tasks, and observed scrolling—to decide whether the proposed split actually helps.

Transfer Challenge

Choose one documentation page you know. Mark every paragraph with its reader job: tutorial, how-to, reference, explanation, or recovery. Then choose one collision and write a two-route repair.

Your repair should include:

• the reader and immediate job for each route;
• an explicit promise for each route;
• one concrete detail, example, table, or trace that makes the important claim inspectable;
• a link sentence that names the question answered elsewhere; and
• one trade-off or boundary that your new structure still leaves unresolved.

If a reader can say where to start, what they can do there, and where to go for the next different question, the revision has preserved connection without preserving overload.

Resources

• [ARTICLE] Diátaxis: a systematic approach to technical documentation authoring — Focus: Compare the four documentation forms as responses to distinct reader needs.
• [ARTICLE] Diátaxis: the difference between a tutorial and a how-to guide — Focus: Distinguish a learning experience from task guidance by the reader's situation, not by length or difficulty.
• [TUTORIAL] Google Technical Writing: Documents — Focus: Review scope, audience, and reader expectations before revising a document's structure.

Key Takeaways

• A page fails when its order serves the writer's topic instead of the reader's next job.
• Document modes are promises: tutorial, how-to, reference, explanation, and recovery each support a different kind of work.
• Diagnose a mixed page through reader promise, mode, explanatory order, clarity scale, evidence, and representation.
• Split routes when the reader's job changes, then make the handoff name the next question.
• The trade-off of separation is navigation and maintenance; validate the structure with evidence from real reader behavior.