Your Internal Wiki Is Already Dead: You Just Haven't Buried It Yet

Somewhere in your company's Confluence or Notion instance, there's a page titled something like "Onboarding Guide v2 (UPDATED March 2022)." It has 847 views, a handful of comments from people who no longer work there, and at least three broken links to a Slack channel that got archived during a reorg. Nobody's touched it in fourteen months. But it's still showing up in search results when your newest hire tries to figure out how to get their dev environment running.

This is the documentation graveyard. Every company has one. Most companies have several.

The frustrating part isn't that it exists — it's that it didn't have to. Someone put real effort into that wiki. There were good intentions, dedicated sprints, maybe even a documentation day where the whole team blocked their calendars. And still, the rot set in.

So what's actually going on?

The Incentive Problem Nobody Talks About

Here's the uncomfortable truth: writing documentation and maintaining documentation are two completely different jobs, and most engineering cultures only reward one of them.

When you ship a feature, there's a pull request, a code review, a deploy, a Slack celebration. When you update a wiki page to reflect a config change from six weeks ago, there's... nothing. No ticket gets closed. No metric moves. Your manager doesn't mention it in your one-on-one. The system treats it as invisible work, so developers — rationally — treat it as low priority.

This isn't a character flaw. It's a structural problem. Engineers aren't lazy; they're responding to the incentives in front of them. And right now, almost every incentive structure in software development points away from documentation maintenance.

Add in the fact that most wikis are organizationally orphaned — nobody "owns" them in any meaningful sense — and you've got a recipe for entropy. Pages accumulate. Nobody deletes anything because what if someone needs it? The signal-to-noise ratio collapses, and eventually people stop trusting the docs entirely. They ask a coworker instead. The coworker becomes a human wiki. The coworker burns out.

What Engineers Actually Do (Be Honest)

Talk to developers at any mid-size company and you'll hear the same pattern. They write documentation when they're forced to — during onboarding setup, post-incident reviews, or when a manager explicitly asks. They read documentation with deep skepticism, always half-expecting it to be wrong. And they update it... almost never, unless a bug report or a confused new hire makes the gap impossible to ignore.

One backend engineer at a fintech startup described it this way: "I trust our docs maybe thirty percent of the time. The other seventy percent I'm cross-referencing with the actual code or just asking someone on the team. At some point you stop even opening the wiki."

That erosion of trust is the real killer. Once your team mentally writes off the documentation as unreliable, you've lost the whole game. Even accurate pages get ignored because nobody can tell them apart from the stale ones.

The "Write-Once" Trap

A lot of documentation culture treats docs like they're a deliverable — something you produce, hand off, and move on from. You write the README when you build the thing. You write the runbook when you deploy it. You write the architecture doc when you make the decision. Then you file it away and never look at it again.

The problem is software doesn't work that way. Code changes constantly. Systems evolve. The runbook that was accurate in Q1 might be dangerously misleading by Q3 if you've changed your deployment pipeline. Documentation that doesn't keep pace with the codebase isn't neutral — it's actively harmful. It sends people down wrong paths with false confidence.

Treating docs as write-once artifacts is a bit like writing tests only at launch and then never running them again. The code drifts, the tests lie, and eventually you stop trusting the test suite. Same dynamic, different file format.

Treating Docs Like Code (For Real This Time)

"Docs as code" has become a bit of a buzzword, but most implementations miss the deeper point. Yes, storing documentation in version control alongside your codebase is good. Yes, using pull requests for doc changes creates accountability. But the real shift is cultural and process-level, not just tooling.

Here's a framework worth stealing:

1. Assign ownership with teeth. Every piece of documentation should have an owner — a specific human, not a team — who is responsible for its accuracy. That ownership should show up in performance reviews. Not as a big deal, just as a real thing that counts.

2. Tie doc updates to code changes. If a PR changes behavior that's documented somewhere, updating that documentation should be part of the definition of done. Not a nice-to-have. Not a follow-up ticket that never gets closed. Part of done.

3. Build in expiration dates. Some documentation tools support this natively; others need a workaround. But every page should have a "last verified" date and a prompt to re-verify after a set interval. If nobody re-verifies it, it gets flagged as potentially stale. This shifts the cognitive load from "is this accurate?" to "has someone checked this recently?"

4. Delete aggressively. This one's counterintuitive, but a smaller, trustworthy wiki beats a massive, unreliable one every time. Build a culture where archiving outdated content is celebrated, not feared. Less is more when "less" means people can actually find and trust what's there.

5. Reward maintenance publicly. Shout out the engineer who cleaned up the onboarding docs in the same channel where you celebrate shipped features. It sounds small. It isn't.

The Deeper Cultural Shift

Ultimately, documentation decay is a symptom of how a team thinks about knowledge. If knowledge lives in people's heads, it leaves when they do. If it lives in a wiki nobody maintains, it's almost as fragile — just slower to disappear and harder to notice.

The companies that get this right tend to share one characteristic: they treat documentation as infrastructure, not overhead. It's not the thing you do after the real work is done. It's part of the real work. It gets resourced, prioritized, and evaluated like everything else that keeps the system running.

Your wiki doesn't have to be a graveyard. But keeping it alive requires treating it like something worth keeping alive — which means building that expectation into how your team works, not just hoping someone will care enough to do it on their own.

They won't. Not without a reason to. Give them one.