We lost a payments engineer named Priya to a competitor in the middle of a PSD2 migration. She gave three weeks' notice, which is generous, and I still remember the sinking feeling because she was the only person who understood why our reconciliation job retried failed settlements exactly four times before parking them in a dead-letter queue. Not three, not five. Four. There was a reason, tied to a specific acquirer's timeout behavior, and it lived entirely in her head.
We got lucky. In her last week she wrote it down, on the wiki, in about 400 words, and that page has been read hundreds of times since. But luck is a terrible operating model. That episode is why I have become slightly obsessive about the team wiki, a tool most engineering leaders treat as an afterthought or, worse, a graveyard.
The cheapest insurance you will ever buy
Every engineering org has knowledge that lives in exactly one person's head. In a regulated fintech, that is not a quirk. It is a risk you are legally and operationally on the hook for. When your auditor asks how you handle chargeback disputes across three card schemes, "ask Dave" is not an acceptable answer, and Dave is on holiday in a place with no signal.
A wiki is the cheapest insurance you will ever buy against this. It costs a few minutes per page and pays out precisely when you are most exposed: during an incident at 2am, during an audit, during the two weeks after someone resigns. I have never once regretted a well-written runbook. I have frequently regretted the ones we never wrote, usually while staring at a Slack thread where four people are guessing at how a system works.
Write it down, or repeat it forever
The tell that you need a wiki is repetition. If you find yourself explaining the same thing twice, that is a coincidence. Three times is a pattern, and a pattern is a document waiting to be written. I have a rule with my team leads: the third time someone asks how to rotate the API keys for our sandbox environment, the answer is a link, and if the link does not exist yet, writing it is now part of answering the question.
This sounds rigid. It is meant to be. The alternative is that your most senior people spend their days as human FAQ endpoints, context-switching out of deep work to answer a question they answered last Tuesday. That is an expensive way to run an engineering team, and it quietly burns out the very people you least want to lose. The wiki is not bureaucracy. It is how you stop paying the same tax over and over.
A wiki is not a document dump
Here is where most wikis die. Someone decrees "we should document everything," people dutifully paste in meeting notes and half-finished design docs, and within six months you have 900 pages, 600 of which are stale, and nobody trusts any of it. A wiki you cannot trust is worse than no wiki, because it wastes time and then betrays you at the moment you rely on it.
I think of a good wiki as having roughly four kinds of pages, and everything else is noise that belongs in a ticket or a chat thread:
- Runbooks — step-by-step for operational tasks: how to fail over the primary database, how to reprocess a stuck settlement batch, how to onboard a new merchant to the test environment.
- Decision records — why we chose Postgres over the managed option we evaluated, why we settled on four retries, what we deliberately decided not to build.
- Domain knowledge — the stuff that is true about our business and our regulators, like how each card scheme handles refunds, or the exact meaning of our internal transaction states.
- Onboarding maps — not a giant page, but a curated trail through the other three so a new hire knows what to read in what order.
Notice what is missing. Meeting minutes. Aspirational roadmaps. The "let's brainstorm" documents. Those have homes elsewhere. The wiki is for durable answers to questions people will actually ask again.
Decisions are the real treasure
If I could only keep one category, it would be decision records, and this is the part people underrate the most. Code tells you what the system does. It almost never tells you why. Six months later, someone looks at that four-retry logic, thinks it is obviously wrong, "cleans it up" to three, and reintroduces a bug that took a week of production pain to diagnose the first time.
A one-paragraph decision record prevents that. It does not need to be a formal architecture document with a template and sign-offs. It needs the context, the options you considered, what you chose, and the trade-off you knowingly accepted. The trade-off line is the important one, because it is honest about the fact that every real decision costs you something.
The most expensive sentence in engineering is "I'm sure there was a reason we did it this way." A wiki turns that sentence into a link.
When we migrated our ledger to double-entry accounting, we wrote a two-page record of why, including the specific edge cases in our old model that made month-end reconciliation a nightmare. A year later a new principal engineer proposed reverting part of it for performance reasons. He read the record first, understood the constraint, and proposed something better instead of relitigating a battle we had already fought. That page paid for the entire wiki by itself.
Ownership beats good intentions
Wikis rot for a simple reason: everybody's responsibility is nobody's responsibility. The fix is not a heroic quarterly "documentation sprint," which is the organizational equivalent of a crash diet and works about as well. The fix is small and continuous ownership.
Every page on our wiki has an owner and a last-reviewed date, right at the top. It is not a heavy process. Once a quarter, our tooling flags pages that have not been touched in six months and pings the owner with one question: still accurate, or delete? Most of the time the answer is a thirty-second "still good, reviewed." Sometimes it is "actually this is dead, kill it," and killing pages is a feature, not a failure. A wiki that shrinks is a wiki that is being maintained.
I would rather have 120 pages I trust completely than 900 I have to second-guess. The trust is the entire product. The moment your team starts double-checking the wiki against the code "just in case," you have lost, and you may as well not have it.
Make it part of the work, not extra work
The single biggest reason documentation does not happen is that it gets treated as a thing you do after the real work, in the mythical free time nobody has. So we moved it inside the work. Our definition of done for anything operational includes "runbook updated or created." A pull request that changes a deploy process but not the deploy runbook gets sent back, same as if it had no tests.
Incidents are the highest-leverage moment of all. Our postmortem template ends with a mandatory question: what page would have made this shorter, and does it exist now? The action item is not "be more careful next time," which is a wish, not a plan. It is "write the runbook that catches this," with an owner and a date. We had a nasty incident where a webhook retry storm from a payment provider knocked over a queue consumer. The lasting output was not a stern email. It was a runbook that has been opened during two later incidents and cut our response time on both.
The onboarding multiplier
New hires are the honest auditors of your wiki. A senior engineer joining my team gets pointed at the onboarding trail on day one and told, bluntly, that finding gaps is part of the job for the first month. If a page is confusing, wrong, or missing, they fix it while they still have beginner's eyes, before they absorb the tribal knowledge that makes the gaps invisible.
The payoff is concrete. Our time-to-first-meaningful-pull-request for new backend engineers dropped from around three weeks to under one after we took the wiki seriously. That is not a soft metric. That is two weeks of a senior salary, recovered every single hire, and it compounds. A new person who can find answers themselves is not pulling a tenured engineer out of flow to ask them.
What I deliberately keep out
A wiki earns trust partly by what it refuses to hold. I keep secrets out entirely, which should be obvious but I have seen credentials pasted into wiki pages more times than I would like. I keep anything with a short shelf life out too, because the fastest way to make a wiki feel stale is to fill it with things that were only true for a sprint.
I am also wary of over-documenting the code itself. Long prose explaining what a function does tends to drift out of sync with the function, and then it lies to you. That belongs in comments and tests, close to the code, where it is more likely to be updated. The wiki is for the stuff that does not live naturally anywhere in the repository: the why, the operational how, the domain rules, the shape of the map. Draw that line clearly and both tools get better.
Conclusion
Here is the thing I did not appreciate for the first decade of my career: a wiki is not really a knowledge-management tool. It is a trust-and-resilience tool wearing a knowledge-management costume. It is the difference between an organization that survives a resignation, a 2am page, or an audit as a routine event, and one that treats each as a small crisis. The specific technology barely matters. The habit is everything. Start with the next incident, or the next time someone asks you the same question a third time, and write one page you would actually want to find. That is the whole practice. Everything else is upkeep.