Institutions Never Die: 64–78% of Documents at Three Top Open-Source Organizations Are Orphans

Data date 2026-09-12 · Metric: link graph (inbound links) · ~8 min read · Published 2026/09/12 21:10

1. The symptom everyone recognizes, nobody measures

Industry commentary keeps producing a version of the same quote: companies spend hundreds of thousands of dollars building a knowledge base and end up with a pile of pages nobody wants to open.

(That one is a secondary, industry-metric statement, not our data. Every first-hand number in this article is in sections 3 and 8 — and all of them are reproducible.)

It's predictable. Writing a policy has an owner and a reward (it looks like management). Deleting a policy has risk (What if we need it later? Who signs off?). So policies only accumulate — until nobody reads them.

The cost shows up elsewhere. The primary source here is McKinsey Global Institute's The Social Economy (2012): knowledge workers spent roughly 19% of the workweek (≈7.6 hours) searching for and gathering information, and another 28% on email. The search time isn't the worst part — the fact that what they find may already be obsolete is. And in 2026 there's a new reader: AI agents will scale stale assumptions faster and further than any human could.

Everyone can say "nobody reads these docs." Almost nobody can put a number on it. Without a number you can't prioritize, you can't verify a fix, and you can't argue with "I'm sure the docs are still useful."

So we built the number.

2. Method: turn "unused" into a ratio using the link graph

Object — every Markdown document in a repository (code and images excluded).

Referenced — at least one other document links to it (relative path, repo-absolute path, wikilink, or static-site reference).

Orphan — zero inbound links.

Orphan rate — orphan documents ÷ all documents.

Three discipline rules we had to write down the hard way:

1. "Orphan" ≠ "useless." It means exactly one thing: no other document uses it as an entry point. A page that is hit daily by a search engine but never linked from another doc is still an orphan here. The metric understates value; that's deliberate — it's a conservative proxy.

2. Never mix metrics. The same directory yields opposite conclusions depending on the metric. From our own docs/: under a runtime read metric (117 files) only 13% were never opened — looks healthy; under a link graph metric (the 65 markdown files in it) 98% are orphans — looks rotten. Both numbers are correct: they answer different questions ("did anyone open it?" vs "does any document point to it?") — and they cover different subsets. Averaging different metrics manufactures false certainty.

3. The metric must match the corpus shape. This is where we made our worst mistakes:

Corpus shape	Link graph	Runtime reads	Note
Link-based (Confluence / Notion / hand-written links)	✅ recommended	needs access logs	lowest bar; this article's metric
Site-generated (Hugo / Docusaurus)	❌ invalid	✅	navigation and index pages are machine-generated, so inter-doc links are meaningless — it's how we voided an 8,215-document sample
Auto-injected (AGENTS.md / CLAUDE.md / MEMORY.md)	❌	❌	must be excluded, otherwise "100% referenced" is an artifact
Code-based (verifiable anchors)	—	—	use anchor-existence instead: "does the reference still point at something real?"

Three metric incidents worth naming, because they shaped the table above:

• Incident ① — substring matching for an exemption rule misclassified headings like "not P0" and "P0 issue", silently skipping content that should have been archived.
• Incident ② — cross-sample data contamination: one sample's number leaked into another sample's report.
• Incident ③ — we applied the link-graph metric to a Hugo-generated site and got a spectacular-looking number that was garbage: the site's navigation and aggregation pages are generated, so documents have no reason to link to each other. We voided the 8,215-document sample and excluded it from every conclusion.

That became a hard rule: if the corpus shape doesn't match the metric, the sample is void and does not count. A reproducible wrong metric is far more dangerous than a correct intuition, because it survives review.

3. Evidence: same metric, three organizations, all above 50%

All sampled from public repositories, 598 to 4,717 documents, one identical metric.

Table 1 — Orphan rate across three organizations (whole-corpus link graph)

Sample	Documents	Orphan rate	Dead weight (bytes)
CNCF TOC (foundation governance docs)	598	68%	82%
Kubernetes community (SIG & contributor docs)	964	64%	65%
GitLab Handbook (a real company's policy corpus)	4,717	78%	73%

"Dead weight" is orphan bytes ÷ total corpus bytes. It matters more than the count: orphans skew large (review reports, assessment documents, meeting-note archives), so removing them frees far more space than the raw ratio suggests.

Table 2 — Kubernetes KEPs: status never dies

KEPs are the best sample of the bunch because each one carries machine-readable status (provisional / implementable / implemented / withdrawn / replaced / superseded…). All 652 of them:

Metric	Value
Zombie drafts (status "in review", untouched > 2 years)	26% (87/333)
Fossilized policies (status "implemented", untouched > 5 years)	30% (87/294)
Touched within the last year	1% (9/652)
Median time since last update	6.5 years
Explicitly marked withdrawn / replaced	3% (21/652)
→ Remaining	97%, parked forever in "in use / in review"

One conclusion we killed ourselves: we hypothesized that withdrawn proposals would show lower reference rates. Measured: 81% zero-reference for withdrawn states vs 77% for active states — a 4-point gap, i.e. noise. Not enough to support a causal claim, so it isn't in our conclusions. What carries information is the status × time table above.

Table 3 — Inside a single organization, a 76-point spread

Averages mislead. We computed the link graph over the whole Kubernetes community corpus, then grouped by directory:

Group	Documents	Orphan rate
mentoring / contributors / sig-node	41 / 98 / 29	20% / 28% / 28% (living policy layer)
communication	45	47% (but 82% of bytes are dead weight)
elections / archive / events	180 / 66 / 99	71% / 86% / 96% (archival layer)

The conclusion is not "the corpus is 75% rotten." It is: reference rates must be stratified by directory type first.

Archival layers (events, archives, meeting-note archives) are structurally high-orphan — their job is to record, not to be referenced. Mixing them into an average with the living policy layer produces a meaningless number, and it leads to the wrong action: archive the whole layer, don't "fix" it item by item.

4. Mechanism: status fields are maintained by humans. Time doesn't lie.

KEPs are already good at this — they have status fields, replacement relations, and a process. But every status field has one fatal precondition: a human has to update it.

When a proposal ships, the author updates the status to implemented (that's a win). When a proposal is abandoned, who goes back and marks it withdrawn? That's admitting failure, following a process, and getting someone to approve it. Nobody.

So the status field stays on the optimistic side forever: 73% parked in "in use / in review", only 3% formally declared dead.

Status is not a trustworthy signal. Time is. Crossing the two gives a sharper metric than the orphan rate:

On the KEP sample: 26% + 30% (zombie drafts + fossilized policies). What makes it useful: it never requires judging whether a document's content is correct — only whether its status claim still holds. The latter is computable.

The same logic applies inside companies. The most common problem in a policy library isn't a wrong policy. It's a policy nobody follows anymore that still says "current."

5. What to do: "main area + archive area + automatic decay"

We're publishing the spec and the findings, not the implementation — because the hard part was never the code. The hard part is being allowed to let a policy die.

1. Two-zone structure

• Main area (the file everyone reads by default): only what is currently valid and in use.
• Archive area (*.archive.md): demoted entries move here verbatim, nothing deleted, with their original line numbers.
• Retrieval: one grep. Archiving isn't deletion — it's lowering default visibility.

This is the single most important design decision: the demotion must be reversible, traceable, and lossless. Otherwise nobody will ever run it.

2. Stable IDs + status fields

One stable ID per entry (for cross-zone references and dedup), plus time and status fields. An entry without an ID can't be referenced, and therefore can't be decayed automatically.

3. Decay criteria (our current values, all tunable)

Criterion	Rule
Protection window	created ≤ 14 days → never demoted (new things are protected first)
Doubtful window	incomplete and untouched > 45 days → doubtful (moved to archive, recoverable)
Completed	→ demotion candidate
P0 / skeleton / institutional memory	never demoted (headers, contracts, design rationale)
Planning-horizon protection	section titled "(a–b months)" → protected while untouched ≤ b×30 days, expires automatically
No creation date	treated as missing metadata, stays in main area, waits for a timestamp backfill (we don't guess)

Two of these were bought with real mistakes:

These thresholds are not universal. 14/45 days are values we calibrated on our own corpus, and a different corpus requires recalibration — we did it once already: for a bug-archive document of the same "to-do" shape, 90 days fit better (its entries naturally live longer). Copying someone else's threshold is treating their experience as your fact.

4. Move, never delete. Idempotent. Index is derived.

• Move, never delete: demotion = verbatim into the archive.
• Idempotent: same input, same result (we get this from ID-based dedup).
• The index is generated from the archive by a script; hand-written ledgers are banned — a hand-maintained ledger is the first thing that rots. It is a policy.

5. Stratify before you act

Back to Table 3: classify directories first, then decide the treatment.

• Living policy layer (highly referenced): normal maintenance.
• Archival layers (structurally high-orphan): archive wholesale, exclude from "decay" statistics.
• Everything in between: go through it with the criteria table above.

6. Boundary conditions: five things you cannot externalize

This approach isn't universal. Our conclusion: memory can be externalized; these five cannot — they aren't memory problems.

Cannot be externalized	Why
Authority	Who gets to decide what is a political question. A system can execute rules; it must never own them
Accountability	When something goes wrong a human must own it; "the system decided" is not a defense
Unverifiable judgment	Policies are full of "as appropriate / reasonable / when necessary" — without a cheap verifier, automated aggregation degrades into averaging
Systemic bias	Organizational bias gets amplified N×, invisibly
Audit requirements	Anonymous automatic traces aren't attributable → you need stable IDs and human sign-off

Put simply: this mechanism solves an attention problem, not an authority problem. It reduces the human attention spent maintaining policy. It does not make decisions for people.

7. We ran it on ourselves

Same metric, applied to the documentation we maintain ourselves (117 docs, plus a 53-file notes vault):

Sample	Size	Zero-reference rate	Dead weight
Engineering docs	117	12%	170 KB
Notes vault	53	13%	26 KB

Far better than the three public samples (smaller corpora, newer), yet 170 KB is still reclaimable — and those orphan documents are being re-read by every AI session.

Which is the point: every organization should run this once, and it takes a week.

Your first action (within one week)

Rank your existing policies/documents by last-referenced time, and compute:

If it's > 50%, the "policies never die" problem is real and quantifiable in your organization.

No system to deploy, no process to change — a read-only script and an exported link table. Get the number first, then decide whether to fix it.

8. Reproducing this (all data from public repositories)

Metric definition (anyone can reimplement in ~30 lines):

1. Walk every .md in the corpus (skip .git, node_modules, etc., skip files > 500 KB).
2. Extract links from each file: Markdown ](target), [[wikilink]], static-site refs {{< ref "path" >}}.
3. Resolve relative / repo-absolute targets to corpus objects; self-links don't count.
4. Count inbound links per object: 0 inbound → orphan.
5. Orphan rate = orphans ÷ total; dead weight = orphan bytes ÷ total bytes.
6. For grouped stats, compute the graph over the whole corpus first, then group (otherwise you systematically overestimate).

Sources and sample sizes

Sample	Source	Size	Shape
CNCF TOC	github.com/cncf/toc	598	link-based
Kubernetes community	github.com/kubernetes/community	964	link-based
GitLab Handbook	gitlab.com/gitlab-com/content-sites/handbook	4,717	link-based (87% of files contain links)
Kubernetes KEPs	github.com/kubernetes/enhancements	652	proposal type (carries status)
~~Kubernetes website~~	—	8,215	site-generated: metric invalid, sample voided

Data date: 2026-09-12. All public repositories, snapshotted that day; the numbers hold for that snapshot (these corpora change daily).

Closing

We measured three of the best-governed organizations in open source with one ruler. What we found isn't "they manage badly." It's a structural defect shared by every organization:

Policies have owners who create them. Policies have no owner who kills them.

Ant colonies solved this long ago: pheromones evaporate automatically, so what remains is what's still in use. Human organizations never built that half. Which is why every knowledge base, every SOP, every process document converges on the same end state: it only grows, until nobody reads it.

The fix isn't another Knowledge Management Standard. It's giving policy a death mechanism:

If your corpus measures > 50%, send us the number — and your metric. We want to know how this ratio is distributed across real organizations, and valid counterarguments go into the next revision.

All data reproducible; metric and criteria published in full. Run the same measurement on your own corpus — and if you find a hole in our metric, tell us: valid counterarguments go into the next revision.

Contact: [TBD]