Skip to content
allanninal.dev/build
Collaborate

Part 5 of 7 · Broken link reporter series ~5 min read

How the link report is ordered

Everything up to here has been in service of one page of output. This post is about what goes on it, and rather more about what does not.

Key takeaways

  • Grouped by page, ordered by that page’s pageviews, capped at ten pages.
  • Internal breakage is a separate, shorter, always-first section.
  • Unverifiable links get one line, not one line each.
  • The number to watch is broken links on the top twenty pages, and it should trend to zero.
  • The full list is a link, never the message.

What the report says

Weekly link report

  • Internal — 4 broken links across 3 pages. These are on your own site and are listed first regardless of traffic.
  • /pricing — 6 links, 4,100 views/month. Four to a supplier site that moved, two to a PDF that no longer exists.
  • /guides/getting-started — 5 links, 2,800 views/month.
  • Four more pages with 1–3 links each, 400–900 views/month.
  • 102 further pages with broken links, 6 views/month or fewer between them. Full list →
  • 31 links could not be checked (403 or 429 — usually bot blocking). List →

Six lines. The first four are a morning’s work and cover the pages nearly all of the site’s readers see. The fifth exists so nobody thinks the report is hiding anything, and it is a link rather than three hundred rows.

Why cap the length

How the broken link report is grouped, ordered and cappedA vertical chain of five steps entered by a box labelled 347 broken links, confirmed. Step one groups by page, giving one hundred and twelve pages. Step two joins to traffic, using pageviews over the last thirty days from analytics. Step three orders by views, descending. Step four takes ten, and the rest becomes a link. Step five is one page of output that is actionable. A note says ten is not a limit on what is known but a limit on what is asked of somebody.AWS ACCOUNT347 broken linksconfirmedGroup by page112 pagesJoin to trafficpageviews, last 30 daysAnalyticsper pageOrder by viewsdescendingTake tenthe rest is a linkOne page of outputactionableTen is not a limit on what is known. It is a limit on what is asked of somebody.
Fig 1. How three hundred and forty-seven findings become a page somebody reads. The cap is about the reader rather than the data.
  • Machine learning
  • Security & identity
  • Analytics

A report of ten items gets worked through. A report of a hundred and twelve gets skimmed and closed, and the ten most important items in it are never seen because they are interleaved with a hundred that do not matter.

Traffic is doing the heavy lifting

Without it, ordering has to fall back on something weak: the number of broken links per page, or how long they have been broken. Both correlate poorly with whether anybody cares. A page with eleven broken links and four views a year is worth nothing; a page with one and four thousand views a month is worth fixing this morning.

Any analytics source works, and a rough one is fine. The ordering only needs to be approximately right, and the difference between the top page and the hundredth is usually three orders of magnitude, which no amount of measurement error will invert.

The number to watch

The one broken-link trend worth trackingA horizontal row of five boxes. Total broken: three hundred and forty-seven, flat. On the top twenty pages: down from twenty-two to four. That is the number: and it is falling. The long tail: stays, harmlessly. Zero is not the goal: on a site of two thousand pages. A note says a total that never falls is fine, and breakage on pages people read should trend to zero.THE ONLY TREND WORTH TRACKINGTotal broken347, flatOn the top 20 pages22 -> 4That is the numberand it is fallingThe long tailstays, harmlesslyZero is not the goalon a site of 2,000 pagesA total that never falls is fine. Breakage on pages people read should trend to zero.
Fig 2. The one metric worth watching. Total broken links on an eight-year-old site is a number that will never be zero and never should be a target.
  • Machine learning
  • Management
  • Analytics

Setting a target of zero broken links across two thousand pages is how this kind of project gets abandoned. The tail is old blog posts linking to sites that no longer exist, and no amount of work makes it stay fixed, because more of the web goes away every year.

Broken links on the pages that actually get read is a number that can genuinely reach zero and stay there with about half an hour a month, and it is the one that corresponds to anybody’s experience of the site.

Next: what all of this costs to run.

All posts