There is a moment in the life of almost every growing company. Someone, usually well-meaning and well-organised, decides the team needs "a single source of truth," and sets up a wiki. Notion, Confluence, a shared drive — the tool does not matter. For two weeks it is wonderful. Pages bloom. People link things. There is a sidebar.
Then it dies. Not dramatically — it just slowly stops being true. Pages go stale. Nobody trusts that what is written still applies. New information gets shared in chat instead, because that is where people actually are. Six months later the wiki is an archaeological site: layers of half-true documentation that everyone politely ignores. I have watched this happen at company after company, including, early on, my own.
For a long time I thought this was a discipline problem — that good teams kept their wikis alive and undisciplined ones let them rot. I no longer believe that. The wiki dies for a structural reason, and understanding the reason points directly at the fix.
The structural problem: distance from the work
Documentation in a separate tool has to be visited. It is a place you go, deliberately, in addition to the place you do your actual work. And visiting requires remembering it exists, believing it is current, and choosing to make the trip instead of just asking someone in chat.
Every one of those is a small tax, and people avoid taxes. The work happens in the codebase, in the repo, in the daily tools. The wiki sits to one side, across a gap. Knowledge, like water, does not flow uphill across a gap. It pools wherever the work already is — which is why your real documentation is scattered across six months of chat messages, and your beautiful wiki is empty.
Knowledge pools where the work already happens. A wiki sitting to one side of the work is uphill — and knowledge never flows uphill.
Why "just be more disciplined" fails
The standard response to a dying wiki is a campaign: a reminder in the team meeting, a new owner appointed, a push to "keep it updated." This works for about two weeks — exactly as long as the original enthusiasm did — and then fades for the same structural reason it faded the first time.
You cannot out-discipline a structural tax. As long as updating the documentation is a separate act from doing the work, it will lose to doing the work, every time, in every company, no matter how good the people are. The teams whose wikis survive are not more disciplined. Usually they are smaller, or they have one unusually dedicated gardener who has effectively taken on documentation as a second job. Neither is a system you can rely on.
The fix: put the writing where the work is
The documentation that survives at my company has one property in common: it lives inside the work, not beside it. Plain markdown files committed in the same repository as the code they describe. The decision log, the onboarding steps, the why-we-said-no file — all of them are files you cannot avoid seeing when you open the project, because they sit right there next to everything else.
This collapses the distance. There is no separate place to visit, no trip to remember, no gap for knowledge to fail to cross. You update the documentation in the same motion as the work, because they are in the same place, reviewed in the same way, shipped together. The tax disappears not because people became disciplined, but because there is no longer a separate act to tax.
What this means you should stop doing
Stop buying a tool to solve a documentation problem. The tool is almost never the bottleneck, and a new one just creates a fresh empty place to neglect. Stop appointing a documentation owner as though the problem were ownership; you are really just nominating the next person to burn out gardening a thing nobody visits. And stop running update campaigns, which treat a structural problem as a motivational one.
Instead, ask a single question of anything you want documented: where does the work that this describes already happen? Put the writing there. As close to the work as you can get it. If the answer is "in the code," it goes in the repo. If the answer is "in this one drive," it goes in that drive, beside the thing it explains.
The test
Here is how you will know it worked. A year from now, the documentation will still be roughly true — not because someone heroically maintained it, but because keeping it true was never a separate task that could be skipped. It updated itself, in the sense that it updated whenever the work did, because the two were never apart.
That is the whole secret, and it is almost an anti-secret: the best documentation tool is usually not a documentation tool at all. It is wherever your team already works, used slightly more deliberately. The beautiful empty wiki was never a discipline failure. It was a gap, and the fix is to close the gap, not to keep ferrying knowledge across it.