One section answers one question

What it is

An intent-scoped documentation section fulfills one nameable question or user intent: its heading predicts what the reader can resolve, and its body supplies the answer needed for that intent. “One question” does not mean one fact or one paragraph. A complex question can contain prerequisites, causes, steps, exceptions, and subquestions when they serve the same intent and use substructure for navigation.

Nor must every heading be phrased as a literal question. A task or topic heading can form the same contract when it matches real queries, differs from neighboring sections, and is fulfilled by the body.

Why it happens

Search results, contents lists, and deep links commonly target sections rather than a whole narrative. A section mixing unrelated intents may win a keyword match and then bury the answer in irrelevant material. An intent arbitrarily scattered across several sections forces the reader to assemble it across landings. Intent-based boundaries give headings, search indexing, anchors, and body copy a shared retrieval unit, while giving direct entrants enough context to know where they arrived.

Complex questions contain dependencies. Troubleshooting may require symptom, cause, test, and repair; migration may require prerequisites, execution, and rollback. These parts need not become four disconnected sections or one unstructured block. A parent section states the overall question, child headings expose independently nameable sub-intents, and prerequisites are summarized or linked near the landing point. This keeps the answer coherent and its components retrievable.

Studying it

Create query–intent–target-section samples from search logs, support requests, and task interviews. Send participants directly from search, contents, or an external link and ask them to resolve the problem. Record first landing, answer completeness, within-page and cross-page shuttling, continued search, execution errors, and task outcome. Exit is not self-evidently satisfaction; ask for the answer or observe what follows.

Hold factual content constant when comparing merged, split, and parent–child structures, including complex tasks with prerequisites and exceptions. On mobile, test heading visibility after landing, collapsed content, and local context. With screen readers, test hierarchy, target focus, prerequisite-link names, and return position. Existing search-query distributions are partly shaped by current headings, so they cannot alone validate the current section model.

Where it stops holding

Reference material is often organized by object, command, or parameter, and one table can support many queries. It need not masquerade as one question when object boundaries and field semantics are stable. A conceptual argument may also accumulate across sections; a direct landing should reveal prerequisites without copying the entire essay into each part. Legal, safety, and high-consequence procedures must not lose applicable conditions or make the combined consequence invisible merely to create self-contained fragments.

Length and screen count are not the test. A simple intent may need one paragraph; a complex one may need several child sections. Split only where a subquestion can be named, searched, and understood independently. If splitting produces extensive duplication or makes readers shuttle to assemble one decision, keep the material under a shared parent structure.

Applying it

• Maintain an intent contract for each section: target query or task, promised answer, prerequisites, exceptions, independently searchable sub-intents, owner, and version. When the intent cannot be stated internally in one sentence, redraw the boundary rather than mechanically shortening prose.
• Use task or concept language readers will seek, and open with the direct answer or route. Structure complex questions with a parent overview and child headings. When a prerequisite affects safety or correctness, summarize it near a deep-link landing and link the complete account.
• Give every stable intent an anchor identifier independent of displayed heading and language. On rename, split, merge, or version migration, redirect old deep links to the nearest answer and update search indexes and snippets together.
• Validate direct landings from real queries on desktop, mobile, and screen reader. Readers should name the present question, obtain a complete answer, recognize prerequisites, and return to their source. Monitor repeated queries and cross-section shuttling, but confirm causes through task success rather than treating exit as resolution.

Related

• Same group: T3.01.1 Users scan documentation, they don't read it · T3.01.2 Headings, lists, and code blocks carry the scan anchors
• Adjacent: T3.02.1 Organize help by user task, not by feature module · T2.02.2 Creative headings undermine predictability
• Search terms: section granularity · user intent · deep-linkable answer unit