Eight steps, a copyable article template, risk-based review rules, and a setup we rebuilt and tested in AFFiNE.

What changed (Nov 14, 2026): Restructured the guide around eight build steps. Added key takeaways, what to include by team, guidance by team size, common failure causes, an article metadata table, a tool-type comparison, a section on writing for search, review intervals by risk, a section on giving AI agents access through MCP, a four-week pilot plan, and contribution habits. Imported and rebuilt the fictional Cedar Studio starter in the AFFiNE web app and added three dated screenshots and what we found during the import. Added two FAQs, moved the starter download to the step-by-step creation guide, and shortened the self-hosting and licensing notes.
Your onboarding guide is in a Word file, the latest process lives in a spreadsheet, and the explanation everyone needs is buried in a chat thread. Adding an AI assistant will not tell you which version is approved, who owns it, or who should be allowed to read it.
To build a team knowledge base, start with recurring questions, turn trusted answers into linked articles, assign owners, and test whether colleagues can complete real tasks. Then connect AI to that maintained knowledge with explicit permissions and a clear data boundary.
This guide walks through that process: a structure you can copy, a reusable article template, review rules by risk, and a setup we rebuilt and tested in AFFiNE. The goal is company knowledge that people can maintain and AI systems can use responsibly.
Key takeaways
A team knowledge base is a shared, searchable collection of explanations, procedures, decisions, and reference material that helps employees do their work. Each important answer should have a clear owner, a reliable source, and a review date, so readers can judge whether it applies to their situation.
For a broader introduction, see what a knowledge base is. Here, the focus is building one that works in daily operations.
The practical benefits are straightforward: new hires can find their next step, colleagues can reuse decisions instead of reopening them, and specialists can answer a recurring question with a maintained link. Measure these outcomes in your own team rather than assuming savings from a software purchase.
| Type and audience | Typical content | Main requirement |
|---|---|---|
| Internal: employees and approved collaborators | Onboarding, procedures, decisions, troubleshooting | Access control and accountable ownership |
| External: customers, partners, or the public | Product guides, support answers, setup instructions | Clear navigation and an appropriate publishing workflow |
| AI-assisted: people asking through an AI interface | Approved material available to a retrieval system | Permission-aware retrieval, supporting sources, and evaluation |
These categories can overlap. An internal library can support both direct reading and AI answers. A customer help center can be public or restricted to signed-in customers; it is not automatically something you want search engines to index. For the AI-assisted row, our AI knowledge base guide explains retrieval, testing, and common failure modes.
A wiki describes a collaborative way to create linked pages. A knowledge base describes the job those pages perform. A wiki can therefore be a knowledge base when its answers are organized, reviewed, and useful. Our wiki vs knowledge base comparison covers when each model fits.
Start with the questions each team answers repeatedly. The owner column matters more than the content list: an article without a responsible team is the first to go stale.
| Team | Start with | Typical owner |
|---|---|---|
| People operations | Onboarding checklist, leave and expense rules, who to contact for benefits | People operations lead |
| Engineering | Local setup guide, runbooks, incident escalation, architecture decision records | Tech lead or on-call owner |
| Support | Troubleshooting answers, escalation paths, known limitations | Support lead |
| Sales and customer success | Positioning, pricing rules, approved answers to security questionnaires | Revenue operations |
| Product | Glossary, supported workflows and limitations, release notes | Product manager |
| IT and security | Access requests, device setup, acceptable use rules | IT administrator |
For filled-in structures, see these internal knowledge base examples.
| Team size | Start with | Add when you need it |
|---|---|---|
| 5 to 20 people | One Start here page, 10 to 20 task articles, one owner per area | Category pages, once people can no longer scan the Start here page |
| 20 to 200 people | Category landing pages, a knowledge register, reviews scheduled by risk | Permission groups by team, a monthly review of failed searches |
| 200+ people or regulated work | Formal ownership, access groups tested with representative accounts, retention rules | Approval workflows, audit evidence, rules for which content AI may use |
Most knowledge bases fail quietly. People stop trusting them, return to chat, and the library becomes an archive. The causes are usually predictable:
Word documents, Excel workbooks, and PowerPoint decks still have useful jobs. Modern office suites can also support coauthoring, and AI pipelines can extract content from these formats. The problem is relying on disconnected attachments as the company's main way to distribute and maintain knowledge.
An attachment rarely makes its status obvious. A slide can omit the reasoning behind a decision. A spreadsheet can contain a critical rule without explaining its scope. When another copy appears in chat, readers have to reconstruct the context themselves.
The better workflow is to preserve the original where it matters and create a maintained explanation that links back to it.

| Existing material | What to turn into a knowledge article | What to preserve separately |
|---|---|---|
| Word policy document | Plain-language rules, scope, exceptions, and contact | The signed or approved original, when required |
| Excel workbook | Definitions, assumptions, and instructions for using the model | Formulas and calculation logic in the workbook |
| PowerPoint deck | Decisions, rationale, and next actions | The original presentation and relevant visual evidence |
| Chat thread | The agreed answer and why it was chosen | A source reference, subject to access and retention rules |
| Meeting notes | Confirmed decisions and reusable procedures | The original notes or recording where appropriate |
Markdown makes headings, lists, links, and code easy to inspect as text. Semantic HTML can preserve a document's hierarchy and link structure. Structured records give information consistent fields, such as an owner, status, or effective date.
Those properties help an ingestion pipeline identify sections, retain context, and attach useful metadata. They do not guarantee correct AI answers. A beautifully formatted but outdated policy is still a bad source.
For example, a useful article about expense reimbursement names its audience, links to the current policy, explains exceptions, and identifies the approver. A file called expenses-final-v7.docx provides none of that context by its filename alone.
Start with a bounded problem, such as onboarding new support hires or helping engineers handle a recurring incident. A company-wide rollout can come later.
Write down who the first readers are, the questions they need answered, and the task they should complete afterward. Interview a few colleagues and examine repeated requests in the channels your team already uses. Collect the wording people actually use; it will help you write searchable titles.
A useful pilot goal is: “A new teammate can find the approved setup instructions and complete the process without asking the author.” This is something you can observe. “Centralize all knowledge” is too broad to evaluate.
Build a small inventory of existing documents, decks, spreadsheets, and recurring chat answers. For each item, record the question it addresses, its owner, the intended audience, and whether it is current.
Choose one action: keep, rewrite, combine, or archive. Ask the responsible specialist to settle contradictions before migration. If two reimbursement documents disagree, an AI system should not be asked to guess which is policy.
Start with the highest-value recurring questions. Keep restricted material out of the pilot unless its access requirements are understood. Importing everything first creates more cleanup work and makes it harder to know what you can trust.
Use a small number of entry points that employees recognize. Department names can help, but readers should not need to know who owns a process before finding its instructions.
Here is an illustrative starting structure:
Team knowledge base
├── Start here
│ ├── New hire checklist
│ └── How to find answers and suggest corrections
├── Do common tasks
│ ├── Request software access
│ └── Submit an expense
├── Understand our product
│ ├── Product glossary
│ └── Supported workflows and limitations
├── Solve problems
│ ├── Troubleshooting guides
│ └── Escalation procedures
└── Understand decisions
├── Decision records
└── Process changes and their rationale

Create a landing page for each category. Link prerequisites before a procedure, troubleshooting after it, and the governing policy where it matters. Use descriptive anchors such as “request temporary access,” rather than “click here.” Our knowledge base blueprint explores this information architecture in more detail.
Give every article the same small set of fields so readers and search tools can filter them:
| Field | Example | Why it helps |
|---|---|---|
| Article type | How-to, troubleshooting, policy, decision record | Sets the reader's expectation of what the page contains |
| Audience | All staff, support team, administrators | Guides permissions and filtering |
| Owner | IT administrator | Tells readers who can confirm or correct the answer |
| Status | Draft, reviewed, archived | Separates working drafts from approved guidance |
| Next review | 2026-12-15 | Makes stale content visible |
| Tags | access, onboarding, VPN | Adds the synonyms people search with |
Keep the tag list short and agreed in advance. Ten tags that everyone uses consistently help search more than a hundred that each writer invents.
Evaluate tools using a sample of your own material: one procedure, one table, one diagram, and one restricted document. Ask both a frequent writer and an occasional contributor to update them.
Look for comfortable editing, useful search, collaboration, portable content, and a deployment model your organization can operate. If your team likes Notion-style block editing, check whether the alternative feels natural to those same contributors. A theoretically perfect repository is not useful if updating it requires a specialist every time.
| Tool type | Fits when | Watch for |
|---|---|---|
| Shared drive or document suite | Files already live there and every reader has an account | Search returns files rather than answers, and ownership is invisible |
| Wiki | Many contributors need linked pages | Page sprawl when there are no owners or review dates |
| All-in-one workspace | You want documents, tables, and diagrams in one place | Structure depends on conventions your team has to agree on |
| Dedicated knowledge base or help center | You need built-in verification or a public help center | Another tool to maintain, often priced per seat |
For a broader comparison, use our knowledge base software buyer's guide. If where the data lives is a hard requirement, compare hosted and self-hosted knowledge bases before the pilot. Keep the pilot focused on the workflow, including import and export quality, rather than a long checklist of features you may never use.
Start with the answer or expected outcome. Follow it with prerequisites, steps, exceptions, and a next action. Readers should not have to work through a long introduction before learning what to do.
Use question or task titles: “How to request production access” is more helpful than “IT information.” Define unfamiliar terms. Explain what success looks like and where to go if the instructions fail.
Add screenshots when they clarify a real interface step, but keep essential instructions in text. Diagrams need a written explanation so their meaning survives text extraction. The Zendesk documentation team's content guidance similarly emphasizes consistent templates, clear writing, ownership, and technical review.
Most readers arrive through search, whether in the workspace, a chat tool, or an AI assistant. A few habits make answers findable:
Give each important article a named owner or responsible team, a status, a last-reviewed date, and a next review date. The person who knows the subject should verify the answer; an editor can improve clarity afterward.
Separate drafts from approved guidance. A status label helps readers understand maturity, but it is not a security control. Enforce access using the workspace and document permissions available in your deployment, and test them with representative accounts. Our team knowledge base security guide lists the checks to run.
Set the review interval by risk, not by a single company-wide schedule:
| Risk | Examples | Suggested review |
|---|---|---|
| High | Security, access, compliance, pricing rules | Every 1 to 3 months, and immediately after any change |
| Medium | Procedures, troubleshooting, onboarding | Every 3 to 6 months |
| Low | Glossary, background, decision records | Every 6 to 12 months, or when a reader reports a problem |
These intervals are starting points; adjust them to how fast your processes change. A decision record is a historical document. Review whether it is still in force, and record a new decision instead of rewriting the old one.
Link to the maintained article when answering a question in chat. If the answer needs changing, update that page instead of attaching another copy. Make suggesting a correction easier than creating a competing document.
An AI knowledge base commonly uses retrieval-augmented generation, or RAG: retrieve relevant source passages, then give them to a model as context for an answer. It is different from retraining a model whenever a policy changes. Microsoft's RAG overview explains the separation between retrieval and generation.
Before enabling AI over the library, decide which articles are eligible, how updates and deletions reach the index, and how the system enforces each reader's access rights. Preserve the article title, source reference, review date, and relevant metadata alongside its text.
Use a small evaluation set containing real questions with known answers, a question the library cannot answer, an outdated-policy scenario, and a question about restricted material. Check both the response and its supporting sources. The system should acknowledge missing evidence and avoid exposing inaccessible content.
Treat these as acceptance criteria for any AI integration. For selection criteria, see our guide to AI-powered knowledge base software.
AI use is moving from a chat box on top of the library to assistants and agents that look things up while they work. A developer asks a coding assistant how the team handles an incident; an agent drafts a summary of recent decisions. Some suites now use agents to curate pages as well, as in Microsoft's team knowledge base curated by Copilot and agents for SharePoint.
The Model Context Protocol (MCP) is an open standard for connecting AI assistants to tools and data. It lets a compatible client, such as Claude Code or Cursor, search and read a knowledge base directly. The same rules apply as for any AI integration: expose only approved content, give each client its own credential that you can revoke, keep access read-only unless writing is deliberately tested, and run your evaluation set through the agent too.
In AFFiNE, the MCP server is a workspace endpoint on AFFiNE Cloud and on self-hosted instances with AI features enabled. You create a credential per client in workspace settings; each credential covers one workspace and is read-only by default, with tools for searching documents and reading a full document.
Invite a small group to complete realistic tasks using the new library. Watch where they search, which titles they misunderstand, and whether the instructions actually work. Avoid coaching them toward the right page during the test.
Record failures as specific changes: rename a confusing article, add a missing exception, repair a link, or resolve an ownership gap. Expand the pilot after those issues are addressed.
A four-week pilot might look like this:
| Week | Focus | Done when |
|---|---|---|
| 1 | Scope, source audit, and owners | 10 to 20 priority questions each have a named owner and an approved source |
| 2 | Writing and review | Each priority question has one reviewed article, linked from the Start here page |
| 3 | Reader testing | Three to five readers attempt fixed tasks without coaching, and every failure is logged |
| 4 | Fixes and next scope | Logged failures are fixed and the next team or category is chosen |
Permissions, integrations, and infrastructure can extend this schedule. For the reader test, use a fixed set of questions so results are comparable; the knowledge base starter in our step-by-step creation guide includes eight reader questions and a blank feedback sheet.
Use this template for a procedure or troubleshooting answer. Delete fields that add no value for that article; keep ownership and review information visible.
# How to [complete a specific task]
Owner: [person or responsible team]
Status: [draft / reviewed / archived]
Audience: [who this applies to]
Last reviewed: [YYYY-MM-DD]
Next review: [YYYY-MM-DD]
Source of truth: [link to the approved policy or system]
## Quick answer
[The outcome and the shortest accurate explanation.]
## Before you begin
[Required access, prerequisites, and scope.]
## Steps
1. [Action, including where to take it.]
2. [Next action and expected result.]
3. [How to confirm completion.]
## Exceptions and troubleshooting
[What changes the answer; when to stop and escalate.]
## Related information
[Prerequisite, next task, and supporting source links.]
## Corrections
[How to contact the owner or suggest an update.]
For example, an access-request article should explain eligibility, who approves the request, how approval reaches the administrator, and how access is removed when no longer needed. A newcomer should not have to infer those steps from a screenshot of a form.
Keep the reusable procedure separate from completed requests that contain personal or sensitive information. This gives the team a durable answer without turning every operational record into broadly available knowledge.
AFFiNE is a useful fit when you want collaborative documents, structured tables, and visual explanations in one workspace, with the option to operate the server on infrastructure you control. Its block-based editing offers a familiar starting point for teams accustomed to Notion-style documents.
Think of the workspace as the place where company knowledge is created and maintained. AI is one way to use that knowledge after its quality and access rules are established.
On November 14, 2026, we imported the seven Markdown files from our fictional Cedar Studio starter into a local workspace in the AFFiNE web app, using Import and then Markdown files, and rebuilt them as a working library. Here is what we observed:
start-here, so we renamed every doc.https://new-joiner-first-day.md, which lead nowhere. We replaced them with linked docs by typing @ followed by the doc title.
The fixes took a few minutes for seven files, but they show why you should test a representative sample before a bulk migration: check titles and internal links, not only formatting.

Write a readable procedure in Page Mode. Use an Edgeless canvas to explain a process or decision tree, then put the essential logic into the accompanying text. AFFiNE's Page Mode documentation describes the relationship between the linear document and spatial canvas.
Maintain a knowledge register in a database. In our test register, Title holds the article name, Owner is a text column, Status is a select column with Reviewed and Draft options, and Next review is a date column. Your team keeps these fields current; a date records when a review is due, but it does not run the review. The database documentation explains the underlying block and view model.

For an initial pilot, create a Start here doc, link the first category pages, add a small register, and invite the contributors responsible for those topics. The team knowledge base solution provides a product overview, while AFFiNE templates can help you avoid starting from an empty page.
AFFiNE supports Markdown and HTML workflows alongside its native documents and databases. Use these formats to move readable content between systems, then inspect the result. Import and export support is different from using a folder of plain Markdown files as the application's native storage.
Test representative documents before a bulk migration. Check titles, headings, internal links, images, tables, and any unusual blocks. Preserve originals until the migrated content is reviewed. A Markdown export is useful for text reuse, but it will not carry every database behavior or canvas relationship, and a document export is not a server backup.
For an existing Notion library, start with the Notion-to-AFFiNE import guide. Treat migration as a chance to retire duplicate answers, not merely to reproduce the same clutter in another tool.
AFFiNE AI can assist with drafting and summarizing material. A useful task is to turn meeting notes into a proposed article outline, explicitly marking missing facts. The subject-matter owner should verify the draft before it becomes approved guidance.
Do not let a fluent summary silently change the meaning of a policy or convert an unresolved discussion into a final decision. Keep the source link beside the resulting article so the reviewer can inspect the evidence.
“Local-first,” “self-hosted,” and “local AI” describe different things. Local-first concerns how the application works with local data. Self-hosting concerns who operates the server. Local AI concerns where model processing happens. You need to evaluate each separately.
AFFiNE's self-hosting documentation describes running its server stack on your infrastructure, including sync and collaboration services. This allows a shared workspace without requiring company documents to live in AFFiNE's managed cloud. A workspace stored only on one device, however, is not by itself a multi-user collaboration service. Licensing differs by component, so check the self-hosting options and the license files for your release before choosing a server setup.

| Decision | What your team needs to establish |
|---|---|
| Application and storage | Where the server, database, attachments, and backups run |
| Team access | Who can read, edit, share, and administer the workspace |
| Model processing | Which provider or endpoint receives prompts and retrieved content |
| Retrieval and indexing | Where indexing occurs and how access changes reach the index |
| Other services | Whether email, identity, monitoring, or integrations send data elsewhere |
| Operations | Who owns patching, restore tests, retention, and incident handling |
The current self-hosted AI documentation describes workspace-level Bring Your Own Key configuration and optional custom endpoints. It also identifies provider-specific requirements, including a server-stored Gemini key or an available AFFiNE AI plan fallback for transcription and workspace indexing. Self-hosting AFFiNE does not automatically make every AI feature local.
If your requirement is that company content never reaches an external AI provider, validate each enabled feature and its fallback behavior. Use an approved compatible local integration where supported, or keep a feature disabled until its processing path meets your requirements. Verify network behavior rather than relying on the label “private.”
The value of self-hosting is the ability to design and operate that boundary. It does not remove the need to secure accounts, protect endpoints, or test backups. Our enterprise knowledge base self-hosting guide covers the operational decisions in more detail. For the wider environment, see what an AI workspace includes and the self-hosted AI workspace guide, which separates workspace storage, provider credentials, and model inference.
Schedule reviews according to how quickly the material changes, as in the risk table in Step 6. Review immediately after a process change, an incident, or a reader reporting that an instruction failed.

Start with a few measures you can collect consistently:
| Measure | How to use it |
|---|---|
| Task completion | Observe whether a reader can finish a representative task using the article |
| Time to a useful answer | Time a small sample of real questions before and after the pilot |
| Repeated questions | Track recurring requests and whether a maintained answer exists |
| Review coverage | Divide in-scope articles with a current review by all in-scope articles |
| AI answer quality | Review correctness, source support, abstention, and permission handling |
A simple feedback log is enough to start. If your search system exposes failed queries, use them to identify missing terminology or missing answers. For definitions and ways to collect each number, see our guide to knowledge base metrics.
Measure usefulness before page count. Publishing another hundred articles is not progress if employees still cannot find the current procedure.
A knowledge base stays current only when updating it is part of normal work:
Start with the questions employees ask repeatedly: onboarding steps, access requests, common procedures, troubleshooting, and product terminology. Choose a small set with clear owners and approved sources. Expand after readers can find and use those answers reliably.
A wiki is a collaborative way to create and connect pages. A knowledge base is an organized resource for finding useful answers. A team wiki can serve as a knowledge base when it has clear structure, ownership, and a process for keeping guidance current.
No. Keep originals when their formatting, formulas, signatures, or historical context matter. Extract reusable explanations into maintained articles and link to the source. Start with valuable, frequently used material rather than importing every file without review.
Set the interval by risk. Review security, access, and pricing content every one to three months and after any change; procedures and troubleshooting every three to six months; and stable reference material every six to twelve months, or when a reader reports a problem.
They make text and structure easier to inspect and reuse, but file format alone is insufficient. An AI-ready knowledge base also needs accurate content, useful metadata, source references, appropriate permissions, and a reliable process for updating the retrieval index.
Yes, through integrations such as the Model Context Protocol (MCP), which lets compatible assistants search and read documents. Give each client its own revocable credential, limit it to approved content, keep it read-only unless writing is tested, and check its answers against questions with known answers.
Yes. AFFiNE provides a self-hosted server deployment for shared documents and collaboration on infrastructure you control. Your team operates the server, storage, access configuration, and backups. Validate required features and current licensing for your deployment before expanding the pilot.
Not automatically. External AI providers, storage services, identity systems, and other integrations may still receive data depending on configuration. A fully private workflow requires a verified processing path for every enabled service, including model fallbacks and indexing.
Assign a responsible subject-matter owner to each important article. Contributors can draft updates and an editor can improve clarity, but someone accountable for the process must verify accuracy. Set review dates and provide readers with a simple way to report errors.
Choose one recurring workflow, publish its approved answers, and help colleagues use the same maintained links. Add AI only when you can explain which sources it uses and where the data goes.
AFFiNE brings documents, visual thinking, structured information, and collaboration into that workflow. Download AFFiNE to explore the editor, or review the self-hosting options when your team needs control over its infrastructure.
Editorial note: This guide is published by AFFiNE. The product walkthrough was checked against public AFFiNE documentation on September 23, 2026. On November 14, 2026, we imported and rebuilt the fictional Cedar Studio starter in the AFFiNE web app; the three product screenshots come from that test. Review intervals, team-size guidance, and the pilot schedule are recommendations, not customer case studies or benchmark results. The other illustrations are AI-generated concepts.