Every Two Years, Same Story: Why Engineering Teams Keep Torching Their Own Wikis

Somewhere right now, an engineering manager is making a Slack post that starts with something like: "Hey team, we've decided to migrate off Confluence. We're moving everything to Notion starting next sprint."

Six months later, the Notion workspace is a jungle. Two years after that, someone's pitching GitBook. Or Coda. Or a custom internal tool built by a well-meaning senior engineer who has since left the company.

This isn't bad luck. It's a pattern—one that plays out across startups, mid-sized tech companies, and enterprise engineering orgs with equal reliability. And the cost of this cycle isn't just the migration headaches. It's the accumulated institutional knowledge that gets quietly abandoned every single time you hit reset.

The Migration Feels Like Progress (It Isn't)

Here's the thing about switching documentation platforms: it genuinely feels productive. You're organizing. You're cleaning house. You're finally going to get it right this time.

But what actually happens is that the team invests enormous energy into moving content from one system to another, and in the process, makes dozens of small decisions about what's worth keeping. Stuff that seems outdated gets cut. Context that isn't immediately obvious gets left behind. The new system starts clean—which means it starts empty, in all the ways that matter.

Within a few months, the new platform has the same structural problems as the old one, because the platform was never actually the problem.

So What Is the Problem?

The real issue is almost always one of three things—and usually some combination of all three.

Ownership without accountability. Most internal wikis are everybody's responsibility, which means they're nobody's responsibility. Pages get created during a sprint, never updated, and quietly become wrong without anyone noticing until a new hire follows the instructions and something breaks.

No connection to actual workflow. Docs that live in a separate tab, in a separate headspace, in a separate tool from where real work happens are docs that don't get written. Engineers write code in their IDE, track work in Jira or Linear, communicate in Slack—and then they're supposed to context-switch into a documentation mindset in some other tool entirely. It doesn't happen consistently, and the wiki drifts.

Decay with no feedback loop. When code goes stale, tests fail. When docs go stale, nothing happens—until someone wastes three hours following a setup guide that was accurate eighteen months ago. There's no automated signal that content is aging. No review queue. No expiration date. Just slow rot.

None of these problems are solved by switching to a new platform. They travel with you.

The Hidden Ledger Nobody's Running

Let's talk about cost, because this is where the cycle really stings.

A typical documentation migration at a 50-person engineering org isn't just a weekend project. You've got time spent evaluating new tools (easily 10-20 hours of meetings and demos), time spent migrating content (multiply the number of pages by the average cleanup time per page), time spent re-onboarding the team to the new system, and time spent rebuilding integrations, templates, and permissions structures.

That's before you account for the knowledge that just doesn't make it over. The runbook written by someone who's no longer at the company. The architectural decision log that explains why you made a weird infrastructure choice three years ago. The onboarding notes that accumulated real institutional wisdom over dozens of new hire cycles.

When that stuff disappears—and it always disappears in a migration—someone will have to rediscover it the hard way. That cost doesn't show up in any project tracker.

The Shiny Tool Problem Is Real, But It's Downstream

It's tempting to blame the procurement cycle. New tools are always launching with slicker interfaces and better integrations, and engineering teams are, by nature, curious about new technology. There's also genuine social pressure: if everyone in your network is raving about a new knowledge management tool, it's hard not to wonder if you're missing out.

But the shiny tool problem is usually a symptom, not a cause. Teams migrate when they're frustrated—and frustration builds when documentation isn't working. The new tool is a pressure valve, not a solution.

The real question is: why isn't the current system working? And can that be fixed without blowing everything up?

Breaking the Two-Year Cycle

If you want to stop rebuilding your documentation infrastructure every couple of years, the approach has to address the root causes, not just the symptoms.

Assign real ownership. Every section of your internal wiki should have a named owner—not a team, a person. That person is responsible for keeping their section accurate, which means they also need time budgeted to do it. If documentation maintenance isn't in someone's job scope, it won't happen.

Build docs into the workflow, not alongside it. The best documentation systems are the ones that feel like a natural extension of how the team already works. Pull request templates that prompt for doc updates. Runbooks linked directly from deployment pipelines. Onboarding checklists that live next to the actual onboarding tasks. The goal is to reduce the distance between doing the work and documenting the work.

Create a decay model. Every piece of documentation should have a review cadence—quarterly for frequently-used content, annually for stable reference material. Use whatever tooling you have to flag content that hasn't been touched in a set period. Stale content should be surfaced, not buried.

Set a high bar for migration. Before your team commits to moving platforms, define what success looks like on the current platform if you fixed the ownership and process problems. If you can't articulate why those fixes wouldn't work, you're not ready to migrate—you're just running from the same problem.

The Single Source of Truth Isn't a Tool

Here's the framing shift that actually matters: a single source of truth is an organizational commitment, not a software feature. You can achieve it on Confluence, on Notion, on a GitHub wiki, or on a custom-built internal platform. You can also fail to achieve it on all of those.

The teams that stop rebuilding from scratch every two years are the ones that treat documentation as infrastructure—something that requires ongoing investment, clear ownership, and deliberate maintenance. Not a project you finish. Not a platform you migrate to. A practice you sustain.

The next time someone floats the idea of moving everything to a new tool, ask one question first: what specifically is broken, and why can't we fix it here? If you can't answer that clearly, the migration will just be the start of the next two-year cycle.