Knowledgebase: How to build expert knowledge sharing within your team

Alex Xu — Wed, 24 Jun 2026 04:28:31 +0000

The Pain Point

You are asked to ramp up on a new service. You checked all the internal docs, found some of them, spent one day writing a POC — and it didn't work. Most likely, an outdated doc. Or even worse, the service threw an error you've never seen before. You end up scheduling a meeting with the team member, and it's 2 days later.

Let's take a look from another side. You are a service owner, and your service is on-call heavy. You spend half of the time maintaining the infra, and another half dealing with all the questions coming from the service customers. Yet, new feature requests, new big stories keep coming in, and your manager claims them as the first priority.

"Well, the first priority is always shifting," you sighed.
When you joined the team, you suffered a lot from the outdated documentation, and you were determined to update it, so no one suffers the same as you did. Now you just realized, it's just that you don't get time, and you would never get rewarded for that. There would be people who appreciate it, but it's never from your management.

This post can make the situation slightly better.

Why That Happens

What usually happens is that as the service maintainer, you should be the expert to write the content. However, in reality, the expert is always looking for promotion, working hard on something that would have high impact. While those things that can greatly improve team efficiency are always ignored, for a simple reason: being the firefighter at the scene when an incident happens is visible. Being the one who prevents the incident from ever happening is not.

Can we just let AI handle it? Indeed, the introduction of AI can help us understand things better. Yet, in practice, we found it usually comes with a lot of hallucination, and the more private our project is, the more likely it is to make mistakes.

The Living Knowledge Base

I give a very brief answer: knowledge base. Instead of having a wiki that would be outdated sooner or later, we build a living knowledge base — a tool that provides all the info that the AI needs, and a tool that everyone in the team uses and contributes to.

We use a standard KMS/PKI service as an example:

The basic idea is to save every documentation in reasonably categorized folders. All the AI tools nowadays are intelligent enough to fetch the documentation based on need. The knowledge base works as a minimum common set of all the knowledge of the service owner team. Even two people working on the same project, their understanding may vary, so we only save the "fact" in the knowledge base.

The knowledge base should be self-enhanceable. By that, I mean that users of the knowledge base would be actively contributing knowledge — a discussion on a new feature, an incident, a design doc, and so on. There would be a service expert to review that, but the mainstream AI agents nowadays are already powerful enough to identify and verify misaligned or malformed info.

Why we need the knowledgebase, and how it differs from a internal wiki

How is this different from a conventional wiki? If you look at the detail, it's only a "wiki" with AI support. But if you look at the workflow, it's fundamentally different.

A conventional wiki requires an author to write all the documentation manually. As an IC, if you were the writer, you are just sharing something that you already know, for everyone's good. It wastes the time that you could use to do more impact. In some company culture, it's better to keep the knowledge with you, instead of sharing it.

In this sense, the old wiki is not working, and not updated, because no one would be benefited from updating it.

[Comic Visualization(well, based on true story :) ) Credits to gpt 5]

In the knowledge base pattern, things go differently. The core design principle is: humans only show up at the nodes that require judgment. Everything else is handled by the agent.

Humans reviews in Markdown — it's low friction, anyone can do it. The agent takes that Markdown and renders it into multimodal HTML with architecture diagrams, flowcharts, and code highlighting. Markdown is the source of truth that humans can read and maintain; HTML is the artifact layer that the agent produces. This means the agent's role is not just organizing — it's adding value that no one had time to create manually.

All the devs run their agent based on the knowledge base, and their daily workflow is already in the agent context. So the effort is very small compared to writing a doc in the wiki from scratch: we just write an enhance-knowledge skill and call it. The agent summarizes what was learned during the work session and submits it as a PR. A service expert reviews and approves. Documentation becomes a byproduct of daily work, not a separate task.

How to deal with the outdated documentation? Since the devs use the knowledge base daily, it's almost painless to update the knowledge. We also set up a scheduled staleness detection hook — the agent periodically checks for content that may be outdated and flags it for human review, as part of looping engineering practice.

[What we are doing now ) Credits to gpt 5]

So in this sense, the knowledge base becomes a flywheel. Every developer using the agent is already generating knowledge as a side effect of their daily work. Every approved PR makes the agent smarter. Every smarter agent pulls out better knowledge next time. The cost of contributing is almost zero, and the value keeps stacking up.

Think of it this way: in a wiki, you are writing for others at your own cost. In a knowledge base, you are working for yourself, and the knowledge just follows. One for all, and all for one.

Applications Beyond Documentation

So far we've built some interesting applications on top of this knowledge layer. One is an oncall agent — we gathered all previous incidents as a test set, and the oncall agent generates remediation plans from the knowledge base that should match historical records.

Another is a branch sync tool for cross-team collaboration. It analyzes incoming changes from another main branch, reasons about what the changes are and how they might impact our own service, and provides a dedicated service expert watching all incoming changes 24/7.

The knowledge base is not just a documentation tool — it's an infrastructure layer that other tools can build on.

Some thought at the end

The time of developers happily coding alone is over. The agentic workflow is a new thing, and for new things, nothing can be perfect. We need to change our way of thinking, as engineers and as AI users.