Nobody reads the docs (and it's not their fault)

Every company that's tried to maintain an internal docs/wiki has experienced the same lifecycle. Enthusiastic launch, initial content creation, gradual decline in contributions, creeping staleness, eroding trust, functional abandonment. The wiki still exists. It still appears in search results. Nobody trusts it because the last time someone followed the instructions on a wiki page, the instructions were three months out of date and the resulting afternoon was wasted.

The standard explanation for wiki failure is cultural: people are lazy, nobody values documentation, it's hard to get engineers to write. This explanation is wrong and it leads to the wrong interventions (writing mandates, documentation sprints, contribution gamification) that produce temporary compliance and no lasting change.

Wikis fail for structural reasons, and each failure mode has a structural fix.

Failure mode 1: Staleness

Docs go stale the moment they're written because the system they describe keeps changing while the wiki stays frozen. Every merged PR, every architecture change, every process adjustment makes the wiki slightly less accurate. Nobody is responsible for updating it, and even if someone were, they'd have no systematic way to know which pages are affected by which changes.

The fix: Documentation that updates itself from live activity. When the wiki is generated from GitHub PRs, Slack discussions, and meeting recordings, it stays current because it's derived from the same sources that change the underlying systems.

Failure mode 2: Poor search

Most wiki tools search by keyword, which means finding something requires guessing the exact words the author used. "Authentication flow" doesn't find "login architecture." "Deployment guide" doesn't find "release runbook." After two or three failed searches, users conclude the information doesn't exist and ask a person instead.

The fix: Semantic search that finds content by meaning. You describe what you're looking for and the system finds conceptually relevant results regardless of the specific words used.

Failure mode 3: Contributor-dependent organisation

Each contributor structures their pages differently, names them according to their own conventions, and files them wherever seems reasonable to them at the time. The resulting information architecture reflects the organisational habits of twenty different people rather than the needs of the person trying to find something.

The fix: Consistent structure generated automatically. Self-writing docs follow standard formats (system overviews, decision records, change logs) regardless of who generated the underlying activity. The organisation is determined by the system rather than by individual contributors.

Failure mode 4: Contribution overhead

Writing a wiki page is a separate activity from doing the work the page describes. It requires a context switch from the work to the writing, a judgment call about what to include, and the knowledge that the page will need to be maintained indefinitely. This overhead is always deprioritised under time pressure.

The fix: Contribution that happens automatically. When documentation is generated from the work itself (Slack conversations, PR descriptions, meeting discussions), the contribution happens as a byproduct of the work rather than as an additional task. Nobody writes the wiki. The wiki writes itself.

What a working wiki looks like

A wiki that people actually read and trust has four properties: it's current (updates automatically), it's findable (semantic search), it's consistent (standardised formats), and it's low-effort (no manual contribution required). Most traditional wikis have zero of these properties, which is why nobody reads them.

Self-writing documentation with semantic search provides all four. The result is a knowledge base that earns trust through accuracy and usefulness rather than losing it through staleness and poor search. People read it because it works, not because they're told to.

Frequently asked questions

Should we delete our existing wiki? Keep it as a historical archive and build the new self-writing wiki alongside it. Over time, people will gravitate to the source they trust (the current, searchable one), and the old wiki will become a legacy reference rather than the primary knowledge base.

What about pages that require human writing (style guides, policies)? Some content does require human authorship: company policies, brand guidelines, philosophical documents. These live alongside the auto-generated documentation. The self-writing system handles the factual, operational documentation. Humans handle the narrative and prescriptive content.

How do we get the team to trust the new wiki? Trust is built by accuracy. If people search the wiki five times and get useful, current results five times, they'll keep searching. The trust problem with traditional wikis is that accuracy degrades over time. Self-writing docs maintain accuracy automatically, which maintains trust.

Related reading: What is a knowledge base, Outdated docs are worse than no docs, Why Confluence doesn't work. Related pages: Self-writing docs, Search, Find anything.