Skip to content

Guide the reader through a task

A reader leaves your page, tries a step and comes back. Make the place easy to find. State the result they are working toward, give the starting conditions and keep the sequence visible.

Lead with the method that suits the stated task. Introduce alternatives where a choice matters. A tour of every possible route can wait until someone needs one.

Distinguish requirements from choices

Use an imperative for an action. Use must for a requirement, can for an available choice and might for an uncertain result. Give a reason for a recommendation. Replace should when it leaves the reader unsure whether you mean an obligation, a preference or a prediction.

Fictional example: an export app requires a destination folder, allows a different folder on each run and writes the new files there. It replaces an existing file with the same name.

Meaning Wording
Required input Choose a destination folder before exporting.
Available choice You can use a different folder for each export.
Recommendation Use an empty folder to keep this export separate from earlier files.
Consequence Exporting replaces existing files with the same names. Choose an empty folder to keep the earlier files.
Success check Check that the exported files appear in the chosen folder.

The replacement consequence belongs before the export action. In real documentation, verify that behavior in the named product and version. An uncertain overwrite rule is a research gap to resolve before publishing instructions.

Put information where it is needed

Order a procedure as the reader encounters it: starting state, action, relevant result, next action. Put a condition before the step it governs. State an outcome when the reader needs it to recognize progress or failure.

Technical writing can use the movement of a story without inventing a scene. The action changes something, the reader observes the change, and that observation permits the next action. Keep each link explicit.

A note carries detail that can be skipped safely. A caution identifies a consequence that needs care. A warning precedes an action that can lose work or cause another serious consequence. Name what could happen and how to avoid it. If several notices gather around one step, inspect the sequence before adding another box.

Use action headings for tasks and subject headings for concepts. Mark an optional branch before it begins. Keep required branches in the main path. A concise definition belongs beside the first unfamiliar term if the reader needs it to continue.

Keep reference pages accurate over time

Write the behavior of the documented version. “New” loses its date; “latest” loses its referent. Release notes can describe a supported change, with its version or date. Reference pages usually need the current contract and relevant version limits.

Avoid “not yet” when the only known fact is that a capability is absent. It promises a future on the strength of an adverb. Describe the limit directly; identify an authorized plan as a plan.

Keep a necessary warning or short prerequisite on the page. Link to a longer explanation when the reader can usefully leave the sequence. A link should say where it goes or what it does; tell the reader when it downloads a file or starts an email.

Let the browser respect the reader's choice of tab. Repeat a link only when a separate entry point or a long section makes it useful again.

Before delivery, follow the page from its declared starting state. Check the visible outcome and a relevant recovery path. A fluent read-through cannot establish that the task works.

In the fictional export example, review the draft with an earlier export already in the destination folder. The replacement warning must be visible before the export action. Then read only the numbered steps: they must still lead to the stated result without depending on an optional note.

See accessible content for headings, images and controls, and developer examples for executable material.