Internal Wiki vs Code-Grounded Knowledge: Why Engineering Teams Are Switching
By Fahad Ijaz · · 6 min read
Every engineering team has an internal wiki. Confluence, Notion, GitBook, Slab, the names rotate but the shape is the same: pages, written by humans, organised in a tree, searched by keyword. For documenting team agreements and onboarding checklists, this works. For documenting how the system actually behaves, it has never worked.
What a Wiki Is Good At
Wikis are good at things that change slowly and are written once. Onboarding checklists. The expense policy. The list of channels new hires should join. Anything where a human is the source of truth and the page is just a serialisation of that. For this category, no tool replaces a wiki, and you should not try.
What a Wiki Is Bad At
Wikis are bad at anything the code is the source of truth for. API contracts. Rate limits. Retry behaviour. Which service owns which table. The shape of the queue. The list of feature flags and what they do. All of these change on a different cadence than humans remember to update pages. The result is a wiki that is technically correct on the day it is written and silently wrong by the next sprint.
What Code-Grounded Means
A code-grounded knowledge base does not store answers. It reads the code at query time, finds the relevant pieces, and synthesises an answer with citations to the exact files. There is no page to update, because there is no page. The next time someone asks the same question, the answer is generated again from the current code, which by definition is the current truth.
The Two Together
The healthy pattern is not to delete the wiki. It is to shrink it to what wikis are good at (slow-moving human knowledge) and let the code-grounded layer answer everything else. Within a quarter most teams find their wiki is one tenth the size and is finally being maintained, because what is left is genuinely worth maintaining.
How to Tell Which You Need
If your team's most-asked questions start with 'how does X work', you need code-grounded. If they start with 'where is the policy on X', you need a wiki. Most teams need both, and the mistake is using one tool for both jobs.