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].