105. Structure: writing for scanners

Imagine a help page with four links labeled “Learn more.” They are neatly aligned, equally prominent and equally unhelpful to someone trying to choose one. The layout has achieved consistency. The reader still needs a destination.

Structure makes that destination visible. A heading names the question, a paragraph develops the answer and a link offers a useful next place. The page should reward a quick inspection and a careful read.

Give the page a job

Before arranging the material, finish this sentence: “This page helps the reader…”

The answer might be to export a proof, understand kerning, compare formats or diagnose a failed save. These jobs need different structures.

Page type	Reader's purpose	Useful shape
Tutorial	Learn through a bounded example	Goal, safe starting material, prerequisites, guided actions, results, next task
How-to	Complete a known task	Starting conditions, steps, verification, relevant recovery
Concept	Understand a relationship	Definition or observation, mechanism, example, limits, related tasks
Reference	Look up a contract or value	Exact name, purpose, syntax or fields, values, defaults, effects, failures
Troubleshooting	Investigate an observed failure	Symptom and scope, supported checks, remedies, verification, alternate paths
Decision page	Choose between options	Decision criteria, relevant alternatives, evidence and limits

Use these as organizing choices. A how-to can include the brief explanation needed to perform its steps. A concept page can contain a small example. Split material when the reader has to leave one task to serve another, or when a distinct lookup deserves its own address.

Keep a working note of the page's purpose and boundary. This helps the next editor decide where a newly discovered exception belongs before adding it to the top.

Make the opening useful on its own

A reader may inspect the title and opening before deciding to stay. Name the task or subject and the scope that matters: product, version, platform, prerequisite or audience.

Lead a recovery page with the symptom. Lead a decision page with the relevant choice. An explanatory essay can open with an observation, provided the reader can tell what it is leading toward. A universal rule to put every conclusion first would remove useful discovery from explanations.

In the fictional page at the start of this chapter, replacing “Learn more” with “Choose an export format” lets the reader judge the destination without visiting it. The same principle applies when they arrive: the opening should confirm that the link kept its promise.

Do not promise a “first screen” of fixed dimensions. Screen size, zoom, translation and navigation controls change what fits. Put essential orientation early, then inspect the rendered page at realistic sizes.

Write headings that carry information

A heading makes a claim about the section beneath it. “Choose an export folder” promises a task. “Where exported files are stored” promises an explanation. “Export settings” can be a useful reference heading if that is what readers are looking up.

Avoid a heading that withholds the subject for a joke. A reader seeking recovery should not need to understand a pun before locating the fix. A discursive article may use a more expressive heading, but it still needs to predict the material.

Keep headings in sentence case and use a logical hierarchy. A visual change in size is not a substitute for a real heading level. People navigating by heading lists need the same route as people scanning the page.

Read the headings alone. They should make the page's organization intelligible, even when the full argument requires prose. If two sections have the same heading in different words, check whether they do the same job. If a section cannot be named, find its decision or split its competing subjects.

Give each section enough context

Readers can arrive at an anchor, a search result or a shared section link. Restate enough context to make an important section usable from that point.

Dependent opening: This also excludes them.

Independent opening: PNG export excludes unsaved changes in this fictional application.

The second version identifies the operation and limit. It is deliberately specific to an invented application; the format itself does not establish how an editor handles unsaved work.

Do not reproduce the whole introduction beneath every heading. Repeat the relevant noun, condition or product distinction. Link to substantial prerequisites, and keep short essential ones beside the task.

A section should hold a coherent answer. Its length follows that answer rather than a quota of paragraphs. Add a new heading when the reader's question changes, not simply because the page has scrolled.

Let paragraphs keep their reasoning

A paragraph can move from an observation to an explanation or from a capability to its limit. Keep that movement connected.

Bullets are useful for parallel items. They are less useful when the reader needs to know why one fact changes the meaning of another. A paragraph broken into five bullets may become easier to scan and harder to understand.

For an explanation, give the reader a recognizable subject, develop the relationship and finish at a useful consequence. For a task page, put the point near the start when that helps the reader locate the answer.

Try the first-sentence trail: read only the opening sentence of each paragraph. A trail of generic introductions suggests buried points. A trail of concrete observations leading toward an explanation can be deliberate. Inspect the actual route rather than forcing every paragraph into a miniature summary.

Choose a shape that matches the relationship

Numbers establish sequence or rank. Bullets group items without requiring that sequence. Tables align fields for comparison or lookup.

Before choosing a form, state what it should let the reader do. “Compare supported formats by their limitations” gives a table a purpose. “Make the page look organized” leaves the underlying problem untouched.

Use parallel grammar in a list. Group long collections by meaningful distinctions. Do not split a useful set merely to satisfy an item count.

Give table columns descriptive headers and rows a consistent meaning. A decision table can put the reader's condition first; a reference table may put an exact identifier first. Neither arrangement is universally superior.

Use explicit entries such as “Not supported,” “None” or “Not specified” where those meanings differ. An unexplained dash can stand for all three, which is convenient for the writer and expensive for the reader.

Keep sequences in numbered steps and developed explanations in prose. A long cell may be a sign that the table needs a linked explanation or a different structure. Check narrow screens and assistive reading as well as the desktop view.

Restructure without completing an invented procedure

Here is a fictional source packet:

• Export includes only saved changes.
• File > Export opens a format dialog.
• The dialog offers PDF, SVG and PNG.
• In this application's documentation, PDF is generally recommended for printing and SVG for scalable artwork.
• PNG is a raster format.
• The packet does not describe destination controls, final confirmation or success feedback.

A weak draft puts these facts into one paragraph:

The export feature offers a range of output possibilities, with PDF generally recommended for printing and SVG for scalable artwork, while PNG is a raster format, and you should save first because unsaved changes are excluded before choosing Export from the File menu.

Reorganize by the reader's sequence.

Choose an export format

Save the project first. Export excludes unsaved changes.

1. Choose File > Export. The format dialog opens.
2. Choose the format that fits the intended output.

Format	Guidance established by this packet
PDF	Generally recommended for printing
SVG	Generally recommended for scalable artwork
PNG	Raster format; no destination-specific recommendation supplied

This is a partial procedure. Its structure is clearer, but the source still lacks the final controls and completion state. Mark those gaps in a working draft and verify them before presenting the procedure as complete.

Notice what the table does not do. It does not promise universal printer compatibility, editable SVG output or browser-ready PNG files. Those may sound reasonable; they are not established by this packet.

Layer detail without hiding the condition

Some readers need the answer and a next step. Others need the mechanism or the complete parameter contract. Give each a clear route.

A short answer can lead into a developed explanation. A procedure can link to a reference page after the point where a lookup becomes useful. An overview can route readers to several different tasks.

Keep a prerequisite, purchase condition or warning in the path where it affects the decision. An expandable “More information” section is a poor home for the fact that an action replaces existing work.

Long coherent explanations can remain on one page. Do not divide a reasoning sequence into fragments that force the reader to remember several previous pages. Conversely, do not keep unrelated material together merely because it concerns the same feature.

Offer depth where it answers a new question. Let the reader choose it.

Make links keep their promises

A link asks the reader to interrupt the current passage. Its text should make that interruption worth considering.

Name the destination or action: “Fix failed exports,” “Export format reference” or “Download the sample project.” State when a link downloads a file or begins an email. Let ordinary links respect the reader's browser choices.

The destination's title should make sense of the link that led there. Exact wording is not always necessary, but a reader should not have to investigate whether “Choose a format” has landed on the right page.

Check links in isolation, as a person navigating a link list might encounter them. “Read more” loses its meaning there. A specific destination retains it.

Keep a required fact on the current page if leaving would interrupt the task. Link for depth, a different task or recovery. A repeated link can be helpful at a separate entry point; a link on every occurrence of a noun usually becomes visual noise.

Route common wrong-place readers early. “This page covers the desktop application” can be followed by the appropriate browser-version destination when that page exists. Do not invent an escape route merely to complete the design.

Put warnings before the choice

A warning works only while the reader can still act on it.

Fictional packet: the Delete control removes a shared preset from every project that uses it. No supported duplicate or recovery operation is supplied.

Deleting this preset removes it from every project that uses it. Choose Delete only if you intend that result.

The consequence comes first. The example does not invent a reversible alternative.

Use prominent notices for consequences that merit them. An ordinary format constraint can often sit in the decision table or the sentence before a choice. If every paragraph is labeled important, the page has supplied emphasis without priority.

For troubleshooting, order checks by evidence, effort and risk. A likely remedy may still be a poor first action if it could destroy useful diagnostic information or work. State prerequisites for that remedy before asking the reader to perform it.

Give images a job

A screenshot can locate a control, reveal a state or show the result of an action. A diagram can make a relationship visible. Choose the image for that job and keep the needed instructions in text.

A caption tells the reader what to notice. Alt text supplies the information the image contributes in context. Neither needs an inventory of every visible pixel.

For a fictional screenshot showing the chosen export format:

Caption: PDF is selected in the format dialog.

Alt text: Format dialog with PDF selected.

If adjacent text already conveys everything useful in the image, handle the image according to the publishing system's decorative-image convention. Do not force a screen reader through duplicate scenery.

Preserve exact labels and visible states. Position can supplement a name, but “the button at the bottom right” alone may fail after a layout or language change.

Inspect the result after rendering. Small type, clipped labels and missing text alternatives can defeat an otherwise accurate explanation.

Test routes through the finished page

Read the title, opening, headings, lists and table headers first. Describe the page's promise from those elements. Compare it with the actual content.

Then enter through a middle section. Check whether the local subject, conditions and next action remain clear. Follow a representative task without using explanatory material marked optional.

Open the links and compare their destinations with their labels. A live link can still be wrong. Check the likely wrong-reader route too.

Use the rendered page. Inspect heading levels, list numbering, table behavior, captions and essential notices. Test at a narrow width and with the relevant accessibility tools when those surfaces have changed; a Markdown preview cannot establish every rendering behavior.

Record the specific check and its limit. “All links resolve” is a file-level claim. “The format-reference link reaches the intended format table” is a navigation claim. They are related, but each needs its own evidence.

Keep the route intact as the page changes

A new condition tends to arrive as a note. Another version adds another note. Eventually the notes know more about the task than the steps do.

After a substantive update, recheck the page's purpose, opening and required sequence. Move universal conditions into the main path. Keep optional detail optional. Split a new reader task into its own section or page when that makes the route clearer.

Update incoming link text when the destination's purpose changes. Keep a short private note of the page's intended task, necessary early facts and related references. The next editor should be able to maintain a decision rather than rediscover it.

End a section after its answer and necessary next route. A true fact can still belong somewhere else.

Practice: make the structure answerable

Use the fictional export packet above. Draft a title, opening, section headings and table before writing the full prose.

Review the outline twice:

1. Read as someone who wants to choose a format. Can they find the supported distinctions?
2. Read as someone trying to finish an export. Can they tell that the supplied instructions are incomplete?

Then add the prose, preserving that boundary. Remove one source fact from the packet and revise the structure again. If the table or heading still implies the missing fact, the second pass has exposed an unsupported promise.

Checklist

• The page has a defined task or question and a useful boundary.
• The opening establishes the relevant subject and scope.
• Headings predict their sections and form a logical hierarchy.
• Important sections have enough context for direct entry.
• Lists, tables and prose express the relationships the reader needs.
• Prerequisites and warnings remain in the required path.
• Layered detail adds depth without fragmenting a necessary explanation.
• Links identify useful, verified destinations.
• Images, captions and text alternatives have a specific function.
• The rendered structure has been checked at the level claimed.
• The final page answers its promise without inventing missing steps.