Patching A Flood of 404s | Sentry

Documentation is a roadmap. It gives us the safest route to reliable, performant code. And just as maps are updated to reflect changing infrastructure, we update our documentation to give you the best way to purposefully use Sentry.

In our latest edition of Dogfooding Chronicles, we use Discover to root out the bane of all companies everywhere: the 404 page.

The Problem

As we transitioned to a new documentation structure, all our existing links collapsed, leading to a sea of 404s. A 404 Not Found Response is shown when website content has been removed or moved to another URL. Now for most companies, a 404 on their website is a minor embarrassment. For an error monitoring company, a 404’d page holds a special kind of vocational irony only reserved for shoeless cobblers and vegan butchers.

The Fix

Because we had to reproduce each page from scratch, we couldn’t just patch a bunch of 301 redirects and call it a day. First, we had to understand the scope of the problem. So we used Discover, our insights tool, to not only identify where content was broken but also prioritize that content by user or request count. Then, with Metric Alerts we were notified if any future deployment caused a spike in 404s.

And to nip future 404s in the bud, we built out a homegrown linkchecker to evaluate and identify broken links and anchors, while also requiring that all links must pass the linkchecker test prior to the merge.

Just like some drivers refuse to consult maps, we understand that some developers just flat don’t like reading documentation. And while there are other ways to learn our products’ best practices (like webinars), there’s no better resource to get your code moving in the right direction than documentation. We certainly proved that here, as we used our performance monitoring platform to help us create documentation that, well, helps you use our platform.