Fighting link rot in documentation

Rot is a property of the corpus, not of any one link

Every individual link in your documentation was correct when it was written. Rot happens because the world moves underneath: a vendor reorganises their site, a repository is renamed, a support article is consolidated, an internal tool is retired. No author made a mistake, and yet after two years a meaningful share of the links in any large documentation set no longer resolve to what the sentence around them promised.

Because the cause is external, the response cannot be to write more carefully. It has to be a process that detects breakage continuously and a structure that makes repair cheap when breakage is found.

The silent failure is worse than the broken one

A link returning a 404 is annoying but honest: the reader knows immediately that something is wrong and can search for the real page. The dangerous case is a link that still returns a 200 while pointing at something else entirely — a redirect to a generic home page, a vendor's marketing page that replaced the technical reference, or a documentation site that silently serves its latest version when the versioned URL disappears.

A reader following that link does not know they have been misdirected. They may follow instructions that no longer apply. Automated checkers, which usually only assert a successful status code, will report the corpus as healthy. This is why status checking alone is insufficient and why redirects to home pages deserve specific attention in any check you build.

Route external references through links you control

When documentation links directly to a third-party URL, repairing it means editing every file that mentions it, which for a popular reference may be dozens of places across several repositories. When documentation links through a short link you own, repair is a single destination change and every copy of the reference is fixed at once, including copies in published PDFs and in old versions of the docs that you can no longer edit.

This is the strongest argument for using short links inside documentation, and it is an argument about maintenance rather than about aesthetics. Reserve it for external references and for anything printed or exported, where the ability to repair after publication has the most value.

Use readable, stable slugs

A documentation link should be readable in plain text, because documentation is read in terminals, in diffs, in printed form and in contexts where the anchor text is not clickable. A slug naming the thing it points at is self-describing and survives copying. A random string tells the reader nothing and cannot be sanity-checked by eye.

Keep the slug tied to the concept rather than to the current destination. The link for a vendor's authentication reference should be named for authentication, not for the vendor's current page title, because the page title is the part that will change.

Check on a schedule and route the results to an owner

Run a link checker over the documentation on a regular schedule rather than only in the build that publishes it. External breakage happens between builds, and a check that only runs on change will not notice a link that rotted while nobody was editing that page.

The critical design decision is where the output goes. A report that lands in a build log nobody reads produces no repairs. Route failures into whatever queue the team actually works from, with the file and line included, so fixing one is a small task with an obvious owner rather than a project.

Expect false positives and plan for them

Sites block automated requests, rate-limit aggressively, require a browser-like user agent, or sit behind authentication. A checker that reports these as broken will produce a wall of noise and be switched off within a month, which is worse than not having one.

Maintain an allowlist of hosts to skip or to check less strictly, set a sensible request rate and a generous timeout, and retry before reporting. Treat the checker as something to be tuned rather than installed, and measure its usefulness by whether people still look at its output after six months.

Archive the references that matter most

Some sources disappear entirely: a blog shuts down, a standard is withdrawn, a project is deleted. If a documentation page depends on an external source for its correctness, capture a snapshot in a web archive at the time of writing and note it alongside the link. It costs one action and it is the only recourse when the original is gone.

For internal references, the equivalent is not relying on a link at all. If a fact is short and load-bearing, restate it in your own documentation with a citation, rather than sending the reader elsewhere for a sentence.

Prune as deliberately as you add

Documentation grows monotonically unless someone removes things. Links to superseded tools, retired internal systems and old versions of your own product accumulate and dilute the value of the links that still matter. A periodic pass that deletes rather than repairs is as valuable as the checker.

The question for each stale link is whether a reader today would be better off with it fixed, or with it gone and the sentence rewritten. Frequently the honest answer is the second, and removing it is faster than finding a replacement for a reference nobody needed.