How to build a knowledge base: the platform-first guide

TL;DR. Build a knowledge base in the right order: platform first, audience second, page tree third, the first ten articles fourth, the rest as the team asks for them. Most build-a-KB projects fail because they reverse the order — fifty articles in Google Docs, then a panicked platform shopping spree six months later. This post is the sequence that doesn’t end in that.

The single most repeated mistake in building a knowledge base is starting with the writing. (If you want the shorter answer to what a knowledge base actually is, our what is a knowledge base explainer covers the definition and the four types.) A team kicks off a KB project, assigns three people, and writes thirty articles in Google Docs in the first month. Month two: the docs sprawl, nobody can find anything, the team starts shopping for KB software, picks a tool, imports the thirty articles, and discovers that the structure that worked in folders doesn’t survive the import. Half the articles get re-written, the project loses momentum, and the KB becomes the folder of broken links the team avoids by year three. This post is the order of operations that doesn’t produce that outcome.

Why most build-a-KB projects fail

The pattern is consistent. Three things go wrong, usually in this order:

Writing starts before the page tree exists. Articles pile up with no shared where does this live? convention, and the first thirty pages all need to be re-parented later.
The platform decision gets deferred to month six. The team uses Google Docs because it’s free and we’ll pick a tool later, and the later never arrives without months of migration work.
The success metric is the page count. We wrote 47 articles is a vanity number; the team opened the KB 312 times this week is the load-bearing one. Counting the wrong thing produces the wrong outcome.

Reverse all three. Pick the platform first, build the page tree second, define opened as the success metric, then write.

The seven-step recipe

Build a knowledge base in this order. Each step takes between an hour and a week; the whole sequence usually fits in a month for a small team and three for a larger one.

Name the audience. Internal team, external customers, or both. The answer changes every other decision below. The internal knowledge base post covers what the internal shape looks like; help- center vendor tools cover the external shape.
Pick the platform. This is the step most guides put last; it belongs first. The platform decides what the page tree can look like, how search will behave, how content will get imported and exported, and what migration costs when you switch later. Decide now, before the team writes its first article anywhere. See our knowledge base software roundup for the shape of the decision.
Draft the page tree. Not the articles — the structure the articles will live in. Top-level spaces / sections should map to areas of work (Engineering, Product, Ops, People) or audiences (Customers, Partners), not to types of artefact. A page tree drafted before writing beats one retrofitted after.
Pick the ten most-asked questions. Not the ones you think are important — the ones your team or your customers actually ask. Pull from a Slack search, a support ticket sample, or a manager’s last-month inbox. Those ten become your first ten articles.
Write the first ten in their final shape. Use the discipline from our how to write a knowledge base article post: one article per question, answer in the first paragraph, screenshots annotated, owner named, linked into the page tree. These ten become the examples the rest of the team will copy.
Open it to the team and watch what happens. Don’t announce a 47-article launch. Open the KB with ten articles, see which ones get opened, which titles get searched, which questions still go to Slack. The Slack questions that didn’t get answered are your next ten articles.
Iterate, don’t expand. Add an article when the team asks for one. Re-write the top-five most-viewed articles every quarter. Surface a last updated date so stale pages show as stale. A KB that grows by reader demand beats one that grows by writer ambition every time.

Seven steps. The sequence matters more than the steps themselves; most guides describe the steps and skip the order.

What to skip when you’re starting

Things people put on the day-one KB roadmap that almost always belong on the day-180 roadmap instead. Cut them; come back to them when the basics are working.

A custom branded portal. Until the KB is being used, the portal is decoration. Use the platform’s defaults.
AI-generated articles. Generated content without a human owner doesn’t pass the who do I ask if this is wrong? test. Get the first ten articles right by hand first; introduce AI assistance once the patterns exist.
A full taxonomy of labels and tags. Two or three load-bearing labels (audience, status) are enough. Most detailed taxonomies turn into tag-soup nobody filters by.
A 47-section table of contents on the home page. A short list of most-opened pages this week, curated manually, beats a complete table of contents that nobody scrolls.
A migration project. If you have existing docs in Google Drive or a folder somewhere, don’t import them all on day one. Import only the ones your top-ten list needs. The rest can come over piece by piece, edited as they’re imported.

The opinion this post stands behind: the platform decision is the first decision. Most build-a-KB projects fail because the team picks the platform last — after thirty pages already exist somewhere else — rather than first. The platform decides what the page tree can look like, how search behaves, what import / export looks like, and what migration costs the day you change your mind. Naming the platform on day one prevents the month-six panic.

Internal vs external: how each affects every step

The audience question changes more than people expect.

Internal KB. Your readers are colleagues with a company badge. They’ll log in once and stay logged in; the audience is finite (the team) and the page tree maps to the team’s shape. Page-tree organisation usually beats search-first for navigation because people learn the page tree. Tools that fit: general-purpose wiki platforms — Confluence, Notion, Raccoon Page. See our corporation wiki and internal knowledge base posts.

External KB. Your readers are paying customers or the public. They arrive via search engine or in-app help, almost never browse, and they expect answer in 30 seconds. Search-first navigation matters more than the page tree; the platform has to handle branded portals, customer-facing URLs, and analytics on what tickets were deflected. Tools that fit: help-center / customer-support software — Zendesk Guide, Intercom Articles, Help Scout Docs, Document360.

Both. Almost every small SaaS company ends up needing both. The sustainable shape is two KBs, one source of truth — the internal KB is the canonical version; the external KB is the customer-safe slice, written by the team that owns the feature. Don’t try to make one platform serve both audiences; the trade-offs cancel.

How to know the KB is working

Three signals say the project is paying back. Three say it isn’t.

Working signals:

The team opens the KB before asking in Slack — the search is the team’s first reflex, not their second.
New joiners stop asking the same questions twice. Each question gets an article; the next new joiner finds it.
The top-ten most-opened articles are the load-bearing ones — the runbooks, the onboarding docs, the policy pages — not random pages.

Not-working signals:

The team is still asking the same five questions in Slack. The articles either don’t exist, can’t be found, or aren’t written in the team’s words.
Page counts grow but views don’t. You’re shipping content nobody opens.
The KB hasn’t been edited in two months. A static KB is a KB the team has given up on.

The work after launch is the iteration loop: watch what gets searched, watch what doesn’t get found, write the missing article, edit the stale one, retire the duplicate.

Raccoon Page is not the only platform you can build a KB on. Confluence, Notion, GitBook, Slite, Tettra, Document360, Zendesk Guide, and a half-dozen others ship working KB platforms. We’re the one built for the platform-decision- first discipline — sub-second loads so the search reflex gets rewarded, keyboard-first navigation so the team can jump anywhere with Cmd+K, public spaces when the internal KB needs a customer-facing slice. The Free tier is three users, one space, a hundred pages, no card — enough to draft the page tree and write the first ten articles, then decide if the platform fits the shape.

Things people actually ask

How long does it take to build a knowledge base? The first ten articles plus the page tree: about a month for a small team. The KB being useful daily: about three months. The KB the team trusts as the source of truth: about a year, and only if the iteration loop runs. The build-once-launch-once mental model is the wrong one.

What’s the difference between building a knowledge base and writing knowledge base articles? Building a KB is the system (platform, page tree, audience, iteration loop). Writing articles is the content that lives inside it. Article-writing comes after the system exists; see our how to write a knowledge base article post for that side of the work.

Should I use a wiki, a help-center, or both? Depends on the audience. Internal team only: wiki. Customer-facing only: help-center. Both audiences: both tools, two KBs, one source of truth.

How many articles should I start with? Ten. The most-asked-questions ten. Resist the urge to ship with forty; you’ll re-write half of them when the page-tree convention shakes out.

Who should own the knowledge base? A single named owner for the whole KB (usually the manager of the team that consumes it most), plus a named owner per article. Ownership-by-committee is the failure mode that explains most abandoned KBs.

What’s the right way to organise a knowledge base? Page tree organised by area of work or audience, not by artefact type. A Runbooks section is fine if your team thinks in artefacts; an Engineering > Services > Service X tree is usually better if they think in what they’re running.

Do I need a knowledge base if my team is small? Under five people: probably not. A shared Google Doc and a running Slack channel cover the use case. Five-to-ten: maybe; start with the free tier of a wiki and three articles. Ten-plus: yes, and the cost of not having one is already real (the same questions get asked twice in two weeks).

Should I migrate existing docs into the new KB? Selectively, not wholesale. Import the ten most-used existing docs and edit them into the new shape. Leave the rest in their current home and let them come over as they’re needed. Wholesale imports usually result in a folder of broken links nobody opens.

How often should I update the KB? Reader-driven, not calendar-driven. Update an article when something changes that it describes; review the top-twenty most-opened articles every quarter; retire articles that have not been opened in six months. Annual review is the wrong cadence — the product changes faster than that.

If you’ve named your audience, picked the platform, and drafted the page tree, the next step is the first ten articles. Our Free tier is three users, one space, a hundred pages, no card — enough to write those ten and watch which ones the team actually opens on Tuesday. Sub-second loads, keyboard-first search, last updated badges that turn red when an article goes stale. Build the system first; the content follows.