"But it was working fine!"

Your docs site is a production system and nobody's maintaining it

“But it was working fine!”

It was working fine. Four years ago.

A client called recently about their docs site. Sphinx four versions behind, dependencies with known security vulnerabilities, deprecated extensions holding the build together, a theme broken on current browsers, and search that had grown noticeably slower.

The launch got budget. Content creation got budget. Someone even set up CI to build and deploy automatically. The team celebrated, then moved on.

Framework upgrades, dependency updates, security patches? Nobody brought them up. There was no line item for “keep the docs site alive,” because it was alive. It was working fine.

Your docs site didn’t break

You just stopped keeping up with everything around it.

Every dependency you don’t update becomes a risk. Every framework version you skip makes the next upgrade harder. None of it is urgent on any given day, and all of it is urgent four years later.

The decay is invisible. The site loads, the search works, the pages render, until one day they don’t. Or they do, just slower, just slightly broken, just enough for users to notice before you do.

The cost equation

Keeping a docs site maintained is routine work. Not always simple, but manageable if you stay current. The problem is that it never wins against everything else on the roadmap.

The actual cost is modest. A few hours a quarter to update dependencies, a CI check for broken links, an annual framework upgrade before you fall too far behind. Call it 20 to 30 hours a year.

Compare that to what neglect cost this client. Their docs were broken for at least three months before anyone flagged it, and the fix took another six weeks. Four and a half months of slow search and a theme that looked off on half the browsers visiting it. All that time, the docs were quietly telling users that this company doesn’t maintain its tools.

Your docs site is a production system

We all understand this for apps. Nobody ships a production app and walks away for four years. There are monitoring tools, dependency bots, upgrade cycles. A docs site has users, dependencies, and security surface area too. It deserves the same care.

Docs sites get none of that. They get launched and forgotten. Then someone calls you four years later wondering why everything is broken.

It has users, dependencies, and security surface area. It deserves the same care.

That client's site is fixed now, and they're on a maintenance plan. The kind of work that never makes headlines, but means nobody has to make that call again.