Your Wiki Is a Museum. The Real Docs Live in One Head.

TL;DR: Your team already agrees the wiki is out of date, and that consensus is exactly why nobody fixes it. The way out is to stop debating doc quality (unmeasurable) and measure doc health: for every area of the codebase that's actively changing, does any doc exist, and has it moved since the code did? That's an afternoon with git, it converts "the wiki is probably stale" into a named list of undocumented areas, and it usually reveals the real documentation system: one person's memory.

A new engineer joins. Week one, they ask where the payments documentation is. Someone laughs - not unkindly, it's just genuinely funny - and says: "the wiki's kind of… ask Dana." And everyone nods, because that is the system. The wiki is a museum: exhibits from two redesigns ago, confident diagrams of services you deleted, plaques nobody dares remove because maybe something still links to them. The real documentation - current, accurate, load-bearing - lives in Dana's head, with no backup schedule.

This pain is special: it's the only engineering problem your whole team agrees on. Nobody defends the wiki. And yet nothing changes, because "our docs are bad" is a mood, not a measurement, and moods don't make it onto roadmaps.

The cost is measured; your docs aren't

The 2024 Stack Overflow survey puts numbers on the mood: 61% of developers spend more than 30 minutes a day just searching for answers or solutions, and 45.2% agree knowledge silos prevent ideas from crossing the org. Multiply half an hour a day across your team and you're paying a documentation debt invoice every single week. You've just never itemized it.

The deeper problem is where the knowledge actually is. Avelino et al. (2016) found 34% of 133 studied systems had a truck factor of exactly 1, meaning a single person whose departure orphans the code. When docs rot, the written map degrades toward that same shape: the areas that change most are documented least, precisely because the person who understands them is too busy changing them to write anything down. The wiki fossilizes; tribal knowledge compounds; and your onboarding process quietly becomes "shadow Dana," which your undocumented codebase is already teaching every new hire the hard way.

Why does nobody measure this? Because everyone aims at the wrong target. Doc quality - is this page clear, complete, well-written - genuinely can't be measured by a machine, so teams conclude documentation can't be measured at all and go back to shrugging. But two proxies are cheap, objective, and brutally informative: presence (does any doc exist for this area?) and staleness (has it been touched since the code it describes changed?). A page can't be good if it doesn't exist, and it probably isn't right if the code has churned for a year since anyone edited it.

How to measure documentation health in one afternoon, free

1. List your active areas. From the last quarter of git history, take the ten to fifteen areas (services, modules, top-level directories) with the most meaningful change. Docs for dead code don't matter; this list is where documentation actually earns rent.
2. Presence check. For each active area: does any current doc exist (README, runbook, architecture note, onboarding page)? Binary, no quality judgment. The first run of this check is usually the finding: a chunk of your most active code has nothing at all.
3. Staleness check. For each doc that exists, compare two dates: when the doc was last touched and when the area's code last materially changed. Docs in the repo make this trivial (git log -1 on both); for wiki pages, use the page history. A doc a year colder than its code is a plausible-looking trap.
4. Adopt delete-or-date. Every page in the museum gets one of two treatments: a visible date and an owner, or deletion. An honest gap beats a confident fossil. A new hire who knows there's no map asks questions; one who trusts a stale map ships a bug.
5. Put docs in the review path. Move living docs into the repo and make "does this change need a doc touch?" a normal review question. Bacchelli & Bird found code review's real outcomes lean toward knowledge transfer and team awareness. Docs that ride the same loop inherit the same heartbeat, which is the whole trick of knowledge transfer that actually sticks.
6. Re-run monthly. One number to track: the share of active areas with a present, non-stale doc. It will start embarrassing. Watching it climb is the point.

Notice what this measurement usually surfaces: the undocumented areas and the bus factor 1 areas are substantially the same list. It's the same failure wearing two costumes, which is why the fix for docs and the fix for knowledge risk (rotation, review, deliberate spreading) overlap so much. When you run a fire drill on your key person, step one of the recovery plan is always "find the docs." Measuring documentation health is how you find out now that the answer would be "there aren't any."

How you'd actually see it

The afternoon audit is honest but perishable: it describes the repo the day you ran it. Busfactor's documentation health runs the same logic continuously and judges it: four measured shares (active areas with any doc, docs not stale, AI-context coverage, commits touching docs), the exact undocumented areas named, and the docs that rotted over churning code, dated and linked, judged against an expert bar. It sits next to the knowledge map, so the "no docs" list and the "one owner" list confront each other on the same screen.

The honest limit, stated up front: this measures presence and git dates, never prose quality. A mediocre page updated yesterday passes; a brilliant page nobody has touched in a churning area gets flagged. That trade is deliberate. The machine finds the gaps and the rot reliably, and your team judges the writing. It's also, as far as we can tell, a measurement nobody else in the category even attempts.

The door

The museum didn't happen on purpose, and no documentation sprint will empty it - sprints produce more exhibits. What changes the game is a measurement that runs monthly and a loop that keeps docs moving with the code. The free audit above takes an afternoon and hands you a named list instead of a shared shrug. If you'd rather the list maintain itself - and rather know today which of your active areas have no map at all - connect your repos and look at the documentation panel first.