Documentation Theater: Organizations That Write a Lot and Whose Docs Are All Dead

• Target audience: Technical writers, documentation owners, and engineering managers in organizations that have a documentation culture on paper but where the documents aren’t alive
• Prerequisites: A working sense of Pattern D from “Implementation Guide for Organizational Context Supply Capability” (the 12 cross-cutting threats)
• Reading time: ~14 minutes (full read) / ~5 minutes (key points)

Overview

Even in organizations that publicly claim to “have a documentation culture,” more than half of the wiki is over 18 months old, and people make wrong decisions based on what’s there. This is documentation theater. There’s a motive to write but no motive to retire, so dead documents accumulate. Dead documents are not just unhelpful — they are actively more harmful than no document at all, because they trigger wrong decisions based on stale information.

This article digs into Pattern D from the sister piece “Implementation Guide for Organizational Context Supply Capability” as a standalone deep-dive. The frame is document lifecycle design — owner / next review / access log / deprecation sprints — and the mechanisms that keep docs alive.

Symptoms: signs you’re staging theater

Typical symptoms:

• The wiki has 10,000 pages, but more than half are over 18 months old
• Search results surface stale pages first; the current information is buried below
• “It’s in the docs” turns out to mean a doc that’s stale and unusable
• Documents written for compliance and audit are unread from the moment they’re created
• “We documented it, the handover is fine” turns out not to translate when the successor reads it
• Page count is reported up to executives, but access logs are not visible

This is the state of a documentation culture that exists in volume but does not function in quality.

Mechanism: motive to write vs. motive to retire

“No motive to retire”

The motive to write is clear: project kickoff, new initiative, compliance requirement, response to a request. But the motive to age out, deprecate, or kill a document is weak:

• Deprecating a doc isn’t credited in performance review
• Nobody wants to take responsibility for the deprecation decision
• “We might need it again later”
• Psychological resistance to disowning your own past work
• Fear that deleting an old doc deletes the knowledge it contained

The result: only the writing flow runs; the retirement flow is stalled. Ten years in, you have ten years of dead documents stacked up.

“Nobody reads it”

Dead documents don’t get read, so nobody notices they’re stale. Things that aren’t read don’t get updated. This is a negative feedback loop: stale → unread → not updated → more stale → even less read.

Documents written for compliance and audit have no readers from day one (only the auditor reads them). They are stillborn.

The active harm of dead documents

Dead documents are not merely useless. They are actively worse than no document:

• Following the old procedure produces real-world inconsistency with the current state
• Past decisions get mistaken for “current decisions” and the decision process gets confused
• New hires learn from stale information
• Feeding them to AI degrades the output through a poisoned context
• “It’s in the docs” gets weaponized as a shield against change

This is the worst harm of documentation theater. As Panopto’s research¹ suggests, 42% of organizational knowledge is individual-specific and never written down — and the remaining 58% that was written can effectively decay to zero if it’s stale. The state can end up worse than not writing at all.

Directions for response

1. Make owner and next-review-date mandatory

Require an owner and a “next review” date on every document:

• Document templates carry an owner field (a role, not a person) and a next-review date
• Documents that miss review automatically pick up a “stale” flag
• After 3 months of stale, they become deprecation candidates

This is the design principle of embedding the retirement path from the moment of writing. To avoid Goodhart runaway from Pattern F, do not turn “owner / review” counts into a KPI.

2. Make access logs visible

Make read counts (access logs) visible, and treat low-access documents as deprecation candidates:

• Display “access count over the past 90 days” on each page
• Pull a monthly list of bottom-percentile pages
• Pages with “0 accesses in 3 months” automatically notify the owner with a request to retire or update

This way, the organization can structurally surface dead documents nobody is reading.

3. Deprecation sprints

Run a deprecation sprint twice a year:

• A focused window of one day to one week
• Consolidate or delete stale, duplicate, and contradictory documents
• The whole team participates (not delegated to one person)
• Publish the list of deleted documents (transparency)
• Drop the “just in case” discipline

This is proactive retirement, not reactive cleanup. Running only the writing flow leads to collapse over a 10-year horizon.

4. Don’t create any volume KPIs

Don’t make “ADR count,” “wiki page count,” or “postmortem count” a KPI (see Pattern F: Goodhart article). Instead:

• Reference count (access log)
• Reuse count (links from other documents)
• 30-day-new-hire access count

These measure qualitative health. Volume metrics produce runaway.

Anti-patterns

Pattern	What happens	Response
Reporting page count to the executive layer	Goodhart runaway, only volume grows	Report access logs instead
“Keep it just in case”	Dead documents accumulate	Explicit retirement during the half-yearly inventory
Tying owner to an individual person	Departures leave docs ownerless	Tie owner to a role (position)
“If it’s in the wiki, we have a documentation culture”	Searchability degrades	Single source of truth per topic (GitLab handbook-first2, Stripe documentation culture3, the Diátaxis 4-quadrant framework4, Docs Like Code5, and The Documentation System6 all serve as references)
Leaving compliance documents alone	Stillborn from day one	Establish “if nobody reads it, don’t write it” as an executive principle
Feeding stale docs to AI	Context degrades	Run a staleness check before AI ingestion

Summary

• Documentation theater emerges from the asymmetry of “motive to write vs. motive to retire”
• Dead documents do more harm than current documents (wrong decisions, inconsistency, new-hire mis-learning, AI degradation)
• Response: mandatory owner and next-review date / visible access logs / half-yearly deprecation sprint / no volume KPIs
• “If nobody reads it, don’t write it” as an executive principle
• In the AI era, staleness checks become more important (feeding stale docs to AI degrades output)

Related articles

• Implementation Guide for Organizational Context Supply Capability: From Facing Problems to Repair — the parent article
• Goodhart’s law: the moment you turn documentation into a KPI, it hollows out — the structure of volume-KPI runaway
• Tool sprawl and the collapse of single source of truth — searchability and documentation
• The myth that AI will read between the lines — the risk of feeding stale docs to AI

References

1. Inefficient Knowledge Sharing Costs Large Businesses $47 Million Per Year — Panopto + YouGov (2018-07). [Reliability: medium-high] ↩︎

2. The importance of a handbook-first approach to communication — GitLab Inc. (continuously updated). The handbook-first philosophy. [Reliability: high] ↩︎

3. From kickoffs to retros and Slack channels — Stripe’s documentation best practices with Brie Wolfson — First Round Review (2023). [Reliability: high] ↩︎

4. Diátaxis: A systematic framework for technical documentation authoring — Daniele Procida (continuously updated). [Reliability: medium-high] ↩︎

5. Docs Like Code — Anne Gentle (continuously updated). The philosophy of operating documentation the same way you operate code. [Reliability: medium-high] ↩︎

6. The Documentation System — Daniele Procida (predecessor of Diátaxis). [Reliability: medium-high] ↩︎