Skip to content

D0002 page-reading-time

Rule: A guide reads in a bounded time.

Code D0002 (stable, never reused)
Id page-reading-time
Category reading
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn a guide longer than one sitting is left half read
small-workspace warn a guide longer than one sitting is left half read
medium warn a guide longer than one sitting is left half read
big warn a guide longer than one sitting is left half read
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
max-minutes number 10 minutes a page may take to read
wpm integer 230 words read per minute
image-first-seconds number 12 seconds the first figure of a page takes
image-min-seconds number 3 seconds every figure takes at least
image-falloff-count integer 10 figures over which the time per figure falls to the floor
pages one of "all", "guide", "reference" "guide" the kinds of page judged

Why

A guide is read from front to back. A page that takes longer than one sitting is left half read, and the reader returns to it without knowing where they stopped. Several shorter pages, each with one purpose, are finished.

Reading time is the page's words divided by wpm, plus time for each figure: the first one costs image-first-seconds, each one after it a little less, down to image-min-seconds after image-falloff-count figures. The result is an estimate. The message names the speed it assumed.

By default only guides are judged. A reference page is looked up, not read through, so its length is no burden.

How to fix

Split the page where its purpose changes: a tutorial, then a page of concepts, then a reference. Move tables of options and long listings to a reference page and link them.

Configure

[lints.page-reading-time]
level = "deny"
max-minutes = 10
wpm = 230
image-first-seconds = 12
image-min-seconds = 3
image-falloff-count = 10
pages = "guide"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(page-reading-time) <reason> (waivers); the code works there too, as in [lints.D0002].