Why everything breaks at 150 people | Falconer Notes<br>Back to NotesAn internal knowledge base holds the IP, secrets, and tribal knowledge that makes up a company’s DNA.<br>So why do knowledge bases usually suck?

Cerebras published an excellent post on how they built their internal knowledge base.<br>It garnered 2.5M views in its first week, which is more than double the views of Anthropic’s post on the history of Claude Code a week earlier.

Despite the power of AI at our disposal, the average knowledge base is more of a trash fire than ever.<br>Yesterday’s knowledge tools are not built for today’s workflows.

I led knowledge management at Stripe and Uber through their hypergrowth phases.<br>I’ve seen how a great knowledge base leads to faster onboarding, greater productivity, higher retention.

In this post, I’ll explain:

why most knowledge bases suck

the anatomy of a great knowledge base

how to roll one out

I. Why most knowledge bases suck

The number one problem with knowledge bases is that there’s no ownership.<br>Without accountability, everything decays.

Secondly, they’re hidden.<br>You can reverse-engineer Stripe’s world-class documentation or study Vercel’s beautiful frontend design because they’re public.<br>You can’t tour another company’s internal knowledge base.

There are three common failure modes within a knowledge base:

There’s no information on the topic.

There’s missing or outdated information.

There are conflicting pieces of information.

Your knowledge base might suck if:

information is scattered and out of date

your agents aren’t getting the right context

many of your questions are still answered by teammates

Like any engineering problem, you should measure the state of your knowledge base to see where the issues are and how you’re improving over time.

Every hard problem needs to start with a quick dopamine hit to hook people into solving it.<br>The best engineers are typically masochists, so they get a dopamine hit from seeing the problems through data.

This is why Falconer built the first knowledge observability tool, Knowledge Health, to solve this exact problem.

II. The anatomy of a great knowledge base

Start with the codebase

Cerebras picked a focused set of data sources for their knowledge base: code, wiki, incidents, Slack.

This is counter to today’s popular kitchen-sink approach of connecting everything and calling it a company brain.<br>The company brain approach is alluring because you get access to more information, but the quality of that information drops drastically when it conflicts with itself.

The best approach is a strong knowledge graph, architected around your most reliable, authoritative source: the codebase.<br>Code is structured, tested, and versioned.<br>LLMs love this context and knowledge graphs feast on it.<br>The proof is in the benchmarks.

From there, move up the ladder of sources.<br>Documentation is often unmaintained and not organized or tested the way code is.

Slack is typically the most popular source, but also the noisiest and most ephemeral.<br>Cerebras rightfully takes into account the surrounding conversation to gather context.<br>But there are two important things Cerebras doesn’t say about Slack.

First, knowledge typically gets trapped in DMs and scattered across channels which agents can’t access.<br>Second, Cerebras stores distilled knowledge chunks in a database, but that isn’t a surface humans can browse, edit, and maintain.<br>Important information from Slack should make its way to documents, since it’s the best collaboration surface for humans and agents.

Re-think search

Great knowledge is useless if no one can find it.<br>Google has billions of queries per day to learn from.<br>But traditional search techniques don’t work within organizations, because the data sets are small.<br>A wildly popular company page or search query might get a couple hundred hits in a week.<br>You cannot optimize search just from usage the way Google can, because the signal isn’t there.

But engineers do constantly ask questions that rhyme, so query popularity within an org follows a power law.<br>You can see the bulk of search topics based on company priorities: release plans, goals, roadmaps, OKRs, incidents.<br>If you track popularity, you can bolster results and answer quality for 80-90% of searches.

There’s a simple, yet powerful principle that leads to great search: when you curate the underlying knowledge, you get much better results.<br>Delete old cruft, consolidate conflicting sources, and update the docs.

Use documents as a reliable source

Cerebras doesn’t spend much time talking about their docs, which according to their graphic is a Confluence wiki feeding the pipeline.<br>However, documents are king!<br>Documents are where ideas are collaborated on, systems are architected, history is gathered, and where the company’s future is defined.<br>Backlinks in docs tell the story of interconnectedness, and are increasingly where agents publish their artifacts and memories from coding sessions.<br>The opportunity is...