Front-Load Useful Point
DOCS-FRONT-LOAD-USEFUL-POINT
Summary
Put the decision, command, invariant, or warning before broad setup. Readers and agents can then use the page without hunting through introductory prose.
Rule
Front-load the useful point.
Why
Readers scan docs for the decision, command, invariant, or warning that matters. If the first paragraph only says what the page will do or gives broad motivation, both humans and agents must search before they can use the page.
Helps
- Improves scanning and makes important commands, contracts, and caveats harder to miss.
Limits
Narrative setup is useful when context changes interpretation. Put that setup after the concrete point or make the first sentence carry both context and conclusion.
Agent Instruction
Front-load the useful point because readers scan docs for the decision, command, invariant, or warning
that matters.Mechanisms
Supported by first-paragraph review, heading review, task-first README structure, and PR feedback that asks what the reader should learn first.