Why this keeps happening
Documentation URLs encode two things: the identity of the topic and the shape of the site. The topic is stable, the shape is not.
Every docs migration changes the shape. Section names get reorganised, versions get prefixed, the generator changes how it slugifies headings. None of those decisions are wrong, and all of them break inbound links.
The links inside your own site get fixed by the build. The ones printed into a release from two years ago do not.
Where it hurts most
- Error messages compiled into binaries, which are read only once shipped.
- Comments and docstrings in released packages, which are versioned in place.
- Printed material such as manuals, quick start cards and labels on hardware.
- Third party blog posts and answers on forums, which you cannot edit at all.
- QR codes on anything physical, which are the most literally read only thing on this list.
Everything on that list has the same property: the reference is fixed at write time and the destination is not.
One indirection
Put a link you control in the middle. digily.dev/err-401 in the error message, and a record you own deciding where that resolves to.
When the docs site moves, you update the record. Every artefact that ever printed that string keeps working, including the ones you cannot reach.
That is the whole idea. It is not clever and it does not need to be. It works because the thing that changes and the thing that is fixed are now separate.
Name it after the concept
The path should describe what the reader wants, not where the page currently lives.
digily.dev/err-401 stays true through every rewrite of the authentication troubleshooting page. digily.dev/docs-v2-auth-troubleshooting is already carrying a version number it will regret.
Keep paths lowercase, hyphenated and short enough to type from a terminal window that somebody is reading off a screenshot. That last constraint rules out more designs than you would expect.
Treat the links as part of the project
Once there are more than a handful, an undocumented set of redirects becomes its own maintenance problem.
- Keep a file in the repository listing every short link and what it means. It does not have to be the source of truth, only a map.
- Create and update links from the release pipeline through the API rather than by hand.
- Review the list when the docs site changes, which is the moment they are most likely to be wrong.
- Check the statistics occasionally. A link with zero requests may be pointing at something nobody can reach.
The honest cost
You are adding a hop, a dependency and a thing to maintain. All three are real.
The hop costs a few milliseconds and only on the first load. The dependency matters, which is why it is worth choosing a provider you can export from and leave. The maintenance is the link list, which is smaller than the search and replace you would otherwise be doing across every release branch.
For links inside your own site that the build already fixes, do not bother. For anything that gets shipped, printed or compiled in, the trade is straightforwardly worth it.