Almost every team has tried internal documentation, and almost every team has watched it decay. The usual diagnosis is that people are lazy about writing. That is rarely the real problem. The real problem is that reading is expensive: to find one answer, someone has to guess which document holds it, open three that do not, and skim a page written for a different purpose. Asking a colleague costs thirty seconds and always works. Documentation only wins when looking something up is faster than interrupting a person.
The Economics Of Asking A Colleague
Consider what actually happens when someone needs to know how refunds above a threshold get approved. Option one: open the wiki, search a term that may or may not match the wording used by whoever wrote the page, scan the results, open the most plausible, discover it covers a related process, try again. Option two: send a message to the person who knows and get an answer in under a minute.
Option two wins every time, and it should. Individually rational, collectively expensive: the knowledgeable person becomes a bottleneck, the answer never gets written down because it was delivered verbally, and the next person repeats the whole cycle. The documentation is not being ignored out of laziness. It is losing a fair contest on speed.
This reframes what to fix. Writing more documents does not change the economics — it makes searching worse by adding more things to sift. The lever is retrieval: make the lookup faster than the interruption and behaviour changes without anyone being asked to try harder.
Search Returns Documents, Questions Need Answers
Traditional wiki search matches keywords and hands back a list of pages. That is a reasonable tool when you already know roughly where the answer lives and just need to navigate there. It is a poor tool when you have a question and no idea which of two hundred documents addresses it.
The mismatch is that people hold questions, not queries. Someone thinks "can I approve this refund myself?" and has to translate that into whatever nouns the document author happened to use — refund policy, approval thresholds, escalation matrix. Every translation step is a chance to miss.
Asking a question directly and receiving the answer, with a link to the document it came from, removes the translation step entirely. The link matters as much as the answer: it lets the reader verify, and it teaches them where that class of knowledge lives for next time.
Write The Answers People Actually Ask For
The instinct when starting a knowledge base is to document comprehensively — every process, every policy, in order. This produces a large body of text with a low hit rate, because the questions people ask are concentrated in a small number of recurring topics.
A better starting point is to spend a week noticing which questions get asked more than once. There will be fewer than you expect, and they will cluster around decisions rather than procedures: what am I allowed to approve, who do I contact when the usual route fails, what do we tell a customer in this situation. Write those first, in the words the asker used rather than the words the process owner would choose.
This also gives an honest test of whether the knowledge base is working. If the same question keeps arriving in chat after it has been documented, the document exists but is not findable, and that is a retrieval problem rather than a coverage problem. Fixing it means better answers to real questions, not more pages.
Keep It Alive Without A Documentation Project
Documentation rots because updating it is a separate task that competes with real work. Nobody schedules an afternoon to revise the wiki, so drift accumulates until the whole thing is untrustworthy — and once people suspect it is stale, they stop reading it, which removes the last signal that it needs updating.
The cheap intervention is to update at the moment of use. When someone answers a question in chat that should have been in the knowledge base, the answer is already written; moving it takes seconds while the context is fresh. That is a habit, not a project.
The second intervention is to let unanswered questions be visible. A lookup that returns nothing is not a failure — it is a precise, timestamped signal that a specific gap exists and someone just needed it filled. Treat those as the backlog and the knowledge base grows along the contours of actual demand instead of someone's idea of completeness.
Frequently asked questions
How much documentation do we need before this is useful?
Far less than most teams assume. Three to five documents covering the questions your team repeats most often are enough to test whether it helps. Comprehensive coverage written up front tends to produce volume without improving hit rate.
What if the answer is not in the knowledge base?
It should tell you so rather than improvise. A clean 'not found' is useful information: it identifies a real gap at the moment someone needed it, which is the best possible prompt to write the missing page.
Does this replace asking colleagues?
No, and it should not try to. It should win the routine, repeated questions so that the conversations you do have are about genuinely novel problems rather than things already settled.
Who should own the knowledge base?
Ownership works best distributed, with the person who answered the question writing it down. A single designated owner becomes the same bottleneck the documentation was meant to remove.
Top comments (0)