I mass-deleted our internal wiki and started over. Twice.
The wiki grew to 400 pages that nobody read. The fix was not better organization. It was aggressive pruning and a decay policy.
Eighteen months into FinanceOps, our engineering wiki had 400 pages. Setup guides. Architecture diagrams. Decision records. Meeting notes. Onboarding checklists. API documentation. Runbooks. Best practices. Style guides. An entire section on Kafka consumer configuration that three people had contributed to and nobody had read since the month it was written.
The wiki was technically comprehensive and practically useless. New engineers could not find anything. Experienced engineers did not bother looking. Everyone defaulted to asking in Slack, which meant institutional knowledge lived in the memories of senior engineers instead of in documentation.
So I deleted it. All of it.
Most of the leadership posts in this phase are me compressing scar tissue into defaults. It also builds on what I learned earlier in “Managing up to a non-technical founder without losing your integrity.” I am less interested in performative management language now and more interested in the boring mechanisms that keep teams aligned when nobody is in a heroic mood.
The First Deletion
I did not warn the team. I archived everything into a zip file, cleared the wiki, and announced it at the Monday standup. The reaction was mixed. Some engineers were relieved. Others were horrified. One person asked if we could at least keep the Kafka runbook. I said no.
The rule for the new wiki was simple: only documentation that meets two criteria gets written.
- Someone is actively blocked without this document. Not theoretically blocked. Actually blocked right now.
- The document will be referenced at least monthly. Not “might be useful someday.” Monthly.
We rebuilt the wiki over the next month. It had 30 pages:
- Twelve architecture decision records, one per major technical choice, following the ADR format
- One living architecture diagram that showed service boundaries and data flow
- Five runbooks for the five most common production incidents
- Three onboarding guides for different engineering roles
- Nine API documentation pages for our external-facing endpoints
Thirty pages. That was it. And every single page was referenced within its first month of existence. New engineers found what they needed. On-call engineers used the runbooks. Architecture decisions were traceable. The wiki was useful for the first time.
The Second Deletion
Six months later, the wiki had grown back to 120 pages. The same entropy that killed the first wiki was eating the second one. People added pages for new features, meeting notes, brainstorming sessions, and reference material that was useful for one week and stale forever after. The monthly-reference criterion was being ignored because nobody was enforcing it.
I deleted it again. Same process. Archive, clear, rebuild. This time, the team was not surprised. A few people laughed. But the same pattern repeated: the rebuilt wiki was lean, useful, and actively referenced.
The Decay Policy
The third time, I added the mechanism that should have existed from the start: an automated decay policy.
- Every wiki page tracks its last view date, not its last edit date. Edits without readers are noise.
- Any page not viewed in 90 days gets automatically moved to an archive section with a banner that says “This page has not been viewed in 90 days. It may be outdated.”
- Any page in the archive for another 90 days gets deleted permanently. No exceptions.
- A monthly report shows which pages are trending toward the archive, giving owners a chance to update and re-reference them.
The decay policy changed behavior. Page owners started thinking about whether anyone would actually read what they were writing. The “let me document this just in case” impulse was replaced by “is this worth maintaining?” The answer was often no, and that was fine.
What I Learned About Documentation
Most engineering organizations treat documentation as an additive process. You write docs. You never delete them. The wiki grows monotonically until it becomes a graveyard of outdated pages that actively misleads anyone who reads them.
By the time I wrote this, the lesson was bigger than the tool or incident. The job had become setting defaults a team could trust, then proving those defaults in systems like lifeos and bisen-apps. That is leadership work, not just technical taste.
Documentation is not an archive. It is a living system. Living systems require pruning, not just growth. If you are not deleting documentation regularly, your wiki is lying to your team.
The FinanceOps wiki now hovers around 40-50 pages. The decay policy keeps it honest. New pages get added when someone is actually blocked. Old pages get archived when they stop being read. The total page count has been stable for four months, which tells me we have found the natural size of our useful documentation.
I wish I had implemented the decay policy before the first deletion. But I am not sure the team would have accepted automated deletion without the experience of seeing how much better a lean wiki works. Sometimes you have to demonstrate the problem dramatically before people accept the solution. Deleting 400 pages in one morning was dramatic. It was also correct.
The mass deletion was not impulsive. It was the result of realizing that a wiki full of outdated documentation is worse than no wiki at all. Engineers were making decisions based on stale information, and the effort required to audit every page exceeded the effort of starting fresh with a clear structure and strict ownership rules. The second wiki survived because every page had an owner, a review date, and a deprecation policy. Documentation that nobody maintains is not documentation — it is a liability disguised as knowledge.