What is a knowledge base and why does your team need one?
A knowledge base is a centralized, searchable repository of your team's documented knowledge - the single place where architecture decisions, operational procedures, onboarding guides, and process documentation live and are maintained. It is the answer to "where is that documented?" - a question that, on teams without a knowledge base, is usually answered with "I think someone wrote it in Confluence... or maybe it was in a Google Doc... check Slack?"
The business case is straightforward. Atlassian's 2024 State of Teams report found that knowledge workers spend an average of 3.6 hours per week searching for information they need to do their jobs. On a team of eight engineers, that is nearly 29 hours per week - more than half an FTE - spent searching instead of building. A well-structured knowledge base does not eliminate search time, but it cuts it dramatically by giving information a predictable home and making it findable through search and navigation.
A knowledge base is not the same as a wiki, although wikis are a common implementation. The knowledge base is the organized body of knowledge itself. The wiki (or Notion workspace, or docs repo, or GitBook instance) is the tool you store it in. This guide focuses on the knowledge base as a practice - how to structure it, maintain it, and make it useful - rather than on any specific tool.
What types of knowledge bases do software teams use?
Different tools serve different knowledge types. Most teams end up with a primary knowledge base supplemented by specialized stores for specific content.
Wiki-based knowledge bases
Tools like Confluence, Notion, and Outline provide rich editing, page hierarchies, and built-in search. They are best for long-form content that non-technical team members also need to access: onboarding guides, process documentation, meeting notes, and company policies. The downside is that they live outside the development workflow - updating a wiki page requires switching tools, which creates friction.
Docs-as-code
Storing documentation as markdown files in the same repository as the code they describe. Tools like GitBook, Docusaurus, MkDocs, or plain markdown in a docs/ folder serve this approach. The major advantage is that documentation changes can be included in the same pull request as code changes - if you change an API endpoint, you update the docs in the same PR. The downside is that non-developers may find the contribution process intimidating.
Hybrid approach
Many teams use both: code-adjacent docs for architecture decisions, API references, and technical specifications (in the repo), plus a wiki for onboarding, process documentation, and cross-functional content (in Notion or Confluence). The key is that each type of knowledge has one canonical home - not two competing sources.
| Approach | Best for | Strengths | Weaknesses |
|---|---|---|---|
| Wiki (Notion, Confluence) | Process docs, onboarding, cross-functional content | Rich editing, accessible to non-devs, good search | Disconnected from code, easy to neglect |
| Docs-as-code (markdown in repo) | ADRs, API docs, technical specs | Versioned with code, same PR workflow, developer-friendly | Intimidating for non-devs, needs build step for rendering |
| Hybrid | Teams with mixed audiences | Right tool for each content type | Must be disciplined about which content goes where |
How should you structure a knowledge base?
The number one reason knowledge bases fail is poor organization. If people cannot find what they need, they stop looking. Good structure makes knowledge discoverable without requiring the reader to know the exact location of every document.
Organize by purpose, not by team
A common mistake is organizing the knowledge base by team: "Backend," "Frontend," "DevOps," "Product." This breaks down immediately because most knowledge spans teams. A deployment runbook is used by backend, frontend, and DevOps. An architecture decision affects everyone. An onboarding guide is read by people joining any team.
Instead, organize by the reader's intent - what are they trying to do?
- Getting Started - environment setup, codebase overview, team norms, access provisioning. The onboarding path.
- Architecture - ADRs, system diagrams, service maps, data flow documentation. The "how does this work?" path.
- Operations - runbooks, deployment procedures, incident response, monitoring dashboards. The "something is broken" path.
- Process - code review standards, release flow, on-call rotation, meeting cadences. The "how do we work?" path.
- API & Reference - API documentation, library usage guides, configuration references. The "what does this do?" path.
Keep it flat
Deep nesting kills discoverability. A page buried three levels deep in a hierarchy will not be found by someone searching. Keep the structure to two levels maximum: top-level section, then pages within that section. If a section grows beyond 20 pages, split it into two sections rather than adding a sublevel.
Cross-link liberally
Documents do not exist in isolation. An onboarding guide should link to the relevant runbooks. An ADR should link to the code that implements it. A process document should link to the templates it references. Cross-linking creates a web of knowledge that allows readers to follow threads of context without knowing the full hierarchy. For practical collaboration patterns around shared knowledge, see our team collaboration guide.
How do you make knowledge findable?
Structure helps people browse. Search helps people find specific answers. A good knowledge base needs both.
Full-text search is non-negotiable
If your knowledge base tool does not have full-text search, switch tools. The majority of knowledge base lookups are search-driven: someone has a specific question and types keywords. Without search, they must browse through the hierarchy - and they will give up before they find the answer.
Naming conventions matter
Document titles should be descriptive and use the terms people actually search for. "Deployment" is a bad title - deployment of what? "How to deploy the API to production" is a good title. "ADR-014" is findable by number but not by topic. "ADR-014: SSE for real-time board sync" is findable by both.
Create an index page
A curated index page - a manually maintained list of the most important documents with one-line descriptions - provides an entry point for people who do not know what to search for. Update it quarterly as part of your knowledge base review.
How do you keep a knowledge base from decaying?
Every knowledge base decays without active maintenance. The rate of decay depends on how fast your systems change - a startup iterating weekly will see docs go stale in months; a stable enterprise system might stay accurate for a year. Regardless of pace, the maintenance system is the same.
Ownership and review cadences
Every document needs an owner and a review cadence. Create recurring cards on a Flux documentation board for each section of the knowledge base. Assign each card to the section owner with a recurring due date: monthly for operations docs, quarterly for process and architecture docs, annually for a full audit.
Archive instead of deleting
When a document is no longer relevant - a deprecated service, a superseded process - archive it rather than deleting it. Move it to an "Archive" section with a note explaining when and why it was retired. This preserves institutional memory without polluting the active knowledge base.
Track staleness metrics
Monitor the percentage of documents that have been reviewed within their cadence. If the number drops below 70%, your maintenance process is failing and needs attention - either by adjusting cadences, reassigning ownership, or reducing the scope of the knowledge base to a maintainable size.
Where does a kanban board fit in knowledge base management?
A kanban tool like Flux is not a knowledge base - it does not replace Notion, Confluence, or your docs repo. What it does is manage the work of building and maintaining the knowledge base. Think of it as the project management layer for your documentation practice.
- Documentation sprint boards track the creation of new docs: what needs writing, who is drafting, what is in review, what has been published.
- Maintenance boards track recurring review tasks: which sections are due for review, who owns them, and whether reviews are on schedule.
- Gap tracking - when a new hire or an incident reveals a documentation gap, a card on the Flux board captures it so it does not get lost.
The knowledge base is the artifact. The board is the workflow that keeps the artifact current. Both are necessary; neither is sufficient alone. For the habits and processes that feed into a healthy knowledge base, see the documentation culture guide.