DEV Community

Daniel Pertu
Daniel Pertu

Posted on

Our article type says "keep it honest" above the reading time, and all eight of them are wrong in the same direction

The long-form pages on Notifio are data, not MDX. Each one is an object in a TypeScript file, and the type has a field for the reading time with a one line instruction above it:

/** Rough minutes, shown under the title. Keep it honest. */
readingMinutes: number;
Enter fullscreen mode Exit fullscreen mode

I wrote that comment. Then I typed the number in by hand eight times. This week I counted the words.

The audit

The content is structured, so counting is not an estimate. Every page is a title, a standfirst, an array of sections each with a heading and a body string array, optional points, an optional callout, plus faqs. Walk all of it, split on whitespace:

const words = (a: Article) => {
  let t = [a.h1, a.standfirst].join(" ");
  for (const s of a.sections) {
    t += " " + s.heading + " " + s.body.join(" ");
    if (s.points) for (const p of s.points) t += " " + p.title + " " + p.body;
    if (s.callout) t += " " + s.callout.label + " " + s.callout.text;
  }
  for (const f of a.faqs) t += " " + f.q + " " + f.a;
  return t.trim().split(/\s+/).length;
};
Enter fullscreen mode Exit fullscreen mode

Eight pages, three on /for/ and five on /guides/:

page                                         claims   words   at 200wpm   over by
/for/students                                    7m    1068        5.3m      1.47x
/for/expats                                      8m    1055        5.3m      1.71x
/for/amsterdam                                   8m     919        4.6m      1.96x
/guides/how-fast-do-rental-listings-go           6m     884        4.4m      1.53x
/guides/how-to-be-first-to-a-rental-listing      7m     906        4.5m      1.74x
/guides/first-message-to-a-landlord              6m     808        4.0m      1.67x
/guides/rental-documents-checklist               5m     695        3.5m      1.62x
/guides/rental-scams-netherlands                 6m    1018        5.1m      1.33x
                                               ----    ----
                                                53m    7353
Enter fullscreen mode Exit fullscreen mode

Eight pages, eight overstatements, zero understatements. Not one of them is low, which rules out sloppiness as the explanation: random guessing scatters in both directions.

The single number that makes it concrete:

7,353 words / 53 claimed minutes = 139 words per minute
Enter fullscreen mode Exit fullscreen mode

Adult silent reading of ordinary prose sits around 200 to 250 words per minute. 139 is roughly read-aloud speed. /for/students says 7 min read above a page you will finish in four and a half, and /for/amsterdam says 8 for a 919 word page, which is the worst of the eight at nearly double.

The ordering is wrong too, which is the more interesting error

If the numbers were a consistent slow-reader estimate, they would at least rank correctly. They do not. Rank the pages by claimed minutes, rank them by word count, and the two orderings agree at about 0.67 on Spearman rho. The clearest disagreement:

/for/amsterdam                  919 words   claims 8m
/guides/rental-scams-netherlands 1018 words  claims 6m
Enter fullscreen mode Exit fullscreen mode

The longer page claims two minutes less. There is no reading model under which that is true. What actually happened is that I typed 8 on the Amsterdam page while the draft was longer, cut two sections, and never went back to the number. The reading time is the one field on these pages that does not fail loudly when the content changes underneath it.

It is printed in 37 places, not 8

This is the part that made me stop treating it as cosmetic. readingMinutes is rendered from three components:

ArticleLayout, line 69     "{eyebrow} ยท {readingMinutes} min read"   8 pages
ArticleLayout, line 206    "{other.readingMinutes} min"             24 related cards
guides/page.tsx, line 79   "{article.readingMinutes} min"            5 index rows
Enter fullscreen mode Exit fullscreen mode

Every article links three siblings, so the wrong number for /guides/first-message-to-a-landlord also appears on five other pages as a badge on its card, plus the /guides index. One hand typed integer, 37 printed instances.

And the badge is doing a job there. On a related card the minute figure is a price tag: it is the only signal of cost next to a title, so inflating it by 1.7x is an argument against clicking a page I wrote specifically to be clicked. The fear that makes people round up ("nobody complains that a page was shorter than promised") has it backwards. Nobody complains, but a visitor deciding between an 8 minute card and leaving does not tell you which way they went.

The fix is nine lines, because the content is already data

The usual excuse for a hand typed reading time is that the content is prose in a CMS and counting it is somebody else's job. Not here. These pages are arrays of strings in the repo, so the function at the top of this post is the fix. Derive the field, keep the override:

// readingMinutes becomes optional on the type: supply it only to override.
export function readingMinutes(a: Article): number {
  return a.readingMinutes ?? Math.max(1, Math.round(words(a) / 225));
}
Enter fullscreen mode Exit fullscreen mode

That turns a number I have to remember to update into one that changes when the page changes, and it keeps an escape hatch for the checklist page, which is the one case where a word count genuinely lies: /guides/rental-documents-checklist is 695 words but most of them are items you will stop and check against your own paperwork, so 3.5 minutes is not the real cost of using it. That is an argument for an override on one page, not for typing eight integers by hand.

The general shape of the bug is worth naming, because it is everywhere in content sites: a field that describes other fields, with nothing connecting them. These pages have 15 required fields and a type that refuses to let a site page be half-built, which I wrote about in Fifteen required fields and no optional ones. The type can force you to supply a reading time. It cannot tell you the one you supplied is 1.7x too high. The only things that catch that are deriving it, or counting it once and being slightly embarrassed.

Top comments (0)