Skip to content

D0001 prose-run-words

Rule: Prose between two visual breaks stays short.

Code D0001 (stable, never reused)
Id prose-run-words
Category reading
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn a long stretch of prose with no heading, figure, table or code block is skimmed, not read
small-workspace warn a long stretch of prose with no heading, figure, table or code block is skimmed, not read
medium warn a long stretch of prose with no heading, figure, table or code block is skimmed, not read
big warn a long stretch of prose with no heading, figure, table or code block is skimmed, not read
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
max-words integer 250 words of prose a reader meets between two headings, figures, tables or code blocks
pages one of "all", "guide", "reference" "all" the kinds of page judged

Why

A reader takes in a page in stretches. A heading, a figure, a table or a code block gives the eye a place to rest and to find its way back. A long run of prose with none of them is a wall: the reader skims it, and the point in the middle of it is lost.

A run is the prose between two visual breaks: headings, code blocks, tables, figures, admonitions, content tabs, and HTML figures, videos, tables and <details> blocks. Paragraphs and list items both count as prose. The budget is in words, so it means the same on any page.

How to fix

Find where the topic turns and put a heading there. Turn parallel facts into a list, a comparison into a table, and a process into numbered steps. A figure that shows what the text describes is a break too.

A reference page whose long prose is right as it is can be left out with pages = "guide"; see Docs as the reader meets them.

Configure

[lints.prose-run-words]
level = "deny"
max-words = 250
pages = "all"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(prose-run-words) <reason> (waivers); the code works there too, as in [lints.D0001].