Knowledge Base

Knowledge Base Creation

Build searchable, maintainable knowledge bases that your team actually uses — turning tribal knowledge into organizational assets.

Core Principles

1. Knowledge Bases Are Products, Not Projects

A knowledge base is never "done." It requires ongoing investment: content creation, curation, cleanup, and promotion. Treat it like a product with a roadmap, owners, and metrics.

2. Search Is the Primary Interface

If users can't find what they need in 2-3 searches, the knowledge base has failed. Invest in search quality, metadata, tagging, and cross-referencing before adding more content.

3. Lower the Barrier to Contribution

The easier it is to write and publish, the more content you'll get. Support markdown, provide templates, reduce review friction for minor edits, and celebrate contributors.

4. Structure for Discoverability, Write for Scannability

Organize content in categories users naturally think in. Use clear titles, descriptive summaries, consistent formatting, and plenty of internal links.

5. Measure What Matters

Track search success rates, popular content, stale pages, and user feedback. Use data to decide what to improve, archive, or create next.

Knowledge Base Maturity Model

Target: Level 3 for most teams. Level 4 for customer-facing or compliance-relevant knowledge bases.

Actionable Guidance

Platform Selection

Decision Matrix

markdownCopy code
## Platform Decision Matrix

| Requirement | GitBook | Notion | Docusaurus | MkDocs | Confluence |
|-------------|---------|--------|------------|--------|------------|
| Version control (git) | ✅ Native | ❌ Manual | ✅ Native | ✅ Native | ❌ Manual |
| Developer-friendly | ✅ | ❌ | ✅✅ | ✅✅ | ❌ |
| Non-technical editors | ✅✅ | ✅✅ | ❌ | ❌ | ✅✅ |
| Self-hosted | ✅ | ❌ | ✅✅ | ✅✅ | ✅ |
| Advanced search | ✅ | ✅ | ✅ (plugin) | ✅ (plugin) | ❌ |
| API / integrations | ✅ | ✅ | ✅ (open source) | ✅ (open source) | ✅ |
| Cost (low) | ❌ (paid) | ❌ (paid) | ✅ (free) | ✅ (free) | ❌ (expensive) |
| Mobile app | ✅ | ✅ | ❌ | ❌ | ✅ |

Setup Comparison

Docusaurus (recommended for developer docs):

bashCopy code
# Quick start
npx create-docusaurus@latest my-docs classic
cd my-docs

# Add search (Algolia DocSearch)
npm install --save @docusaurus/plugin-search-algolia

# Add versioning
npm run docusaurus docs:version 1.0.0

# Build and deploy
npm run build
# Deploy `build/` to any static host

javascriptCopy code
// docusaurus.config.js
module.exports = {
  title: 'My Project Docs',
  tagline: 'Everything you need to build with My Project',
  url: 'https://docs.myproject.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/myorg/myproject/edit/main/docs/',
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
  
  themeConfig: {
    navbar: {
      title: 'My Project',
      items: [
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: 'Docs',
        },
        {
          type: 'docsVersionDropdown',
          position: 'right',
        },
        {
          href: 'https://github.com/myorg/myproject',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_API_KEY',
      indexName: 'my-project',
    },
  },
};

MkDocs with Material theme:

bashCopy code
# Install
pip install mkdocs mkdocs-material

# Create new project
mkdocs new .

# Serve locally
mkdocs serve

# Build
mkdocs build

yamlCopy code
# mkdocs.yml
site_name: My Project Docs
site_url: https://docs.myproject.com
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - search.highlight
    - content.code.copy
    - content.tabs.link

plugins:
  - search
  - tags
  - git-revision-date-localized

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - tables
  - toc:
      permalink: true

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Guides:
    - guides/index.md
    - Configuration: guides/configuration.md
    - Deployment: guides/deployment.md
  - Reference:
    - reference/index.md
    - CLI: reference/cli.md
    - API: reference/api.md
  - Troubleshooting: troubleshooting.md

Content Structuring

The Information Architecture Pyramid

textCopy code
                    ┌─────────────┐
                    │  Home/Landing │
                    │  (Overview)   │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────┴──────┐ ┌─────┴──────┐ ┌──────┴──────┐
    │  Getting     │ │  Guides &  │ │  Reference   │
    │  Started     │ │  Tutorials │ │  & API Docs  │
    └──────┬──────┘ └─────┬──────┘ └──────┬──────┘
           │              │               │
    ┌──────┴──────┐ ┌─────┴──────┐ ┌──────┴──────┐
    │  Quick Start │ │  How-to    │ │  Config      │
    │  Setup Guide │ │  Best      │ │  CLI Ref     │
    │  First Steps │ │  Practices │ │  Changelog   │
    └─────────────┘ └────────────┘ └─────────────┘

Folder Structure Template

textCopy code
docs/
├── index.md                    # Landing page
├── getting-started/
│   ├── index.md               # Overview
│   ├── installation.md        # Setup instructions
│   ├── quick-start.md         # 5-minute tutorial
│   └── first-project.md       # Guided walkthrough
├── guides/
│   ├── index.md               # Guide overview
│   ├── configuration/
│   │   ├── environment.md
│   │   ├── authentication.md
│   │   └── integrations.md
│   ├── deployment/
│   │   ├── production.md
│   │   ├── staging.md
│   │   └── monitoring.md
│   └── best-practices/
│       ├── security.md
│       ├── performance.md
│       └── scalability.md
├── reference/
│   ├── index.md               # Reference overview
│   ├── api.md                 # API documentation
│   ├── cli.md                 # CLI commands
│   ├── configuration.md       # All config options
│   └── troubleshooting.md     # Common issues & solutions
├── tutorials/
│   ├── index.md
│   ├── beginner-tutorial.md
│   └── advanced-tutorial.md
├── contributing.md            # How to contribute to the KB
└── faq.md                     # Frequently asked questions

Page Template

markdownCopy code
---
title: How to [Task Name]
description: Step-by-step guide for completing [task]
sidebar_position: 2
tags: [configuration, deployment, production]
---

# How to [Task Name]

> **Purpose**: [One-line description of what this accomplishes]
> **Prerequisites**: [List of prerequisites or links to them]
> **Estimated time**: [X minutes]

## Step 1: [First Step]

[Description of what to do]

```bash
[Command to run]

Expected result: [What should happen after this step]

Step 2: [Second Step]

[Description]

Verification

[How to confirm success]

Troubleshooting

Related

• Link to related guide
• Link to reference

Copy code

---

### Taxonomy and Tagging

#### Tag Taxonomy Design

```yaml
# Tag taxonomy for a developer knowledge base
#
# Category-based tags follow this hierarchy:
# domain > area > topic

tags:
  # By topic area
  - backend
  - frontend
  - infrastructure
  - security
  - data
  - mobile
  
  # By content type
  - tutorial
  - guide
  - reference
  - troubleshooting
  - faq
  
  # By audience
  - beginner
  - intermediate
  - advanced
  - administrator
  
  # By system/component
  - authentication
  - database
  - deployment
  - monitoring
  - api
  - cli
  
  # By project/team
  - team-alpha
  - team-beta
  - platform

Tagging Guidelines

markdownCopy code
## Tagging Guidelines

### Rules
1. **Every page needs at least 2 tags**: one content type + one topic
2. **Max 5 tags per page**: too many tags dilute search
3. **Use existing tags**: check existing tags before creating new ones
4. **Keep tags lowercase**: consistent casing improves search
5. **Use nouns, not verbs**: `deployment` not `deploying`

### Tag Combinations
| Page Type | Required Tags | Recommended Tags |
|-----------|--------------|------------------|
| Getting started guide | `tutorial`, `beginner` | `setup`, `first-steps` |
| API reference | `reference`, `api` | `backend`, `integration` |
| Troubleshooting guide | `troubleshooting` | Component-related tags |
| Best practices | `guide`, `best-practices` | Domain-specific tags |

Automated Tag Suggestions

pythonCopy code
# Example: suggest tags based on page content
def suggest_tags(content: str, existing_tags: list) -> list:
    """
    Suggest relevant tags based on page content analysis.
    """
    keywords = {
        "install": ["getting-started", "setup"],
        "config": ["configuration", "setup"],
        "deploy": ["deployment", "devops"],
        "error": ["troubleshooting", "errors"],
        "api": ["api", "integration"],
        "security": ["security", "authentication"],
        "database": ["database", "data"],
        "monitor": ["monitoring", "observability"],
    }
    
    suggestions = set()
    content_lower = content.lower()
    
    for keyword, tags in keywords.items():
        if keyword in content_lower:
            suggestions.update(tags)
    
    # Limit to most relevant
    return list(suggestions)[:3]

Search Optimization

Content That Ranks in Internal Search

markdownCopy code
## Writing for Search Discovery

### 1. Start with the Question
Use the question as the title so it matches what users search for:

✅ "How do I reset my password?"
✅ "Why is my deployment failing with error 503?"
❌ "Password Reset Procedure"
❌ "Deployment Error Analysis"

### 2. Include Synonyms in the First Paragraph
Users search with different vocabulary:

> "If your login fails or you can't sign in to the dashboard,
> you may need to reset your password. This guide covers
> password recovery, credential reset, and account access
> restoration."

### 3. Use Descriptive Headings
Headings are heavily weighted in search:

✅ "### Resolving Database Connection Timeouts"
❌ "### Issue Resolution"

### 4. Add a Summary Block
```markdown
> **TL;DR**: If you see "Error 503 Service Unavailable" during
> deployment, your application server is overloaded. Scale up
> your instance or check for memory leaks before redeploying.

Copy code

#### Search Configuration

```yaml
# MkDocs Material search configuration
plugins:
  - search:
      lang:
        - en
      separator: '[\s\-_]'
      min_search_length: 3
      prebuild_index: true  # Offline search support

# Docusaurus search (Algolia)
themeConfig:
  algolia:
    appId: YOUR_APP_ID
    apiKey: YOUR_API_KEY
    indexName: your-docs
    contextualSearch: true
    searchParameters:
      hitsPerPage: 10
      attributesToSnippet:
        - 'title:30'
        - 'content:200'

Knowledge Base Maintenance

Content Health Dashboard

markdownCopy code
## Content Health Metrics

Track these monthly:

| Metric | Target | How to Measure |
|--------|--------|---------------|
| Stale pages (>6 months since update) | <10% | Git log / last modified dates |
| Orphaned pages (no inbound links) | <5% | Backlink analysis |
| Search failure rate | <15% | Search analytics |
| Pages with no tags | <2% | Tag metadata audit |
| Reader satisfaction | >4/5 | Feedback widget |
| Pages per contributor (monthly) | >2 | Contribution tracking |

Stale Content Detection

yamlCopy code
# GitHub Action: Find stale docs
name: Stale Content Check
on:
  schedule:
    - cron: '0 6 1 * *'  # First day of every month

jobs:
  stale-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Find stale pages
        run: |
          echo "## Stale Documentation (not updated in 6 months)" > stale-report.md
          echo "" >> stale-report.md
          
          for file in $(find docs -name "*.md" -type f); do
            last_commit=$(git log -1 --format="%cd" --date=short -- "$file")
            if [[ $(date -d "$last_commit" +%s) -lt $(date -d "6 months ago" +%s) ]]; then
              echo "- [$file]($file) — last updated $last_commit" >> stale-report.md
            fi
          done
      
      - name: Create Issue
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('stale-report.md', 'utf8');
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'Monthly Stale Content Report',
              body: body,
              labels: ['documentation', 'maintenance']
            });

Content Lifecycle

textCopy code
                 ┌─────────────┐
                 │   DRAFT     │  ← Created by contributor
                 └──────┬──────┘
                        │
                 ┌──────┴──────┐
                 │  REVIEW     │  ← Peer/SME review
                 └──────┬──────┘
                        │
                 ┌──────┴──────┐
                 │  PUBLISHED  │  ← Live in knowledge base
                 └──────┬──────┘
                        │
              ┌─────────┴─────────┐
              │                   │
       ┌──────┴──────┐    ┌──────┴──────┐
       │   UPDATED   │    │  ARCHIVED   │
       └──────┬──────┘    └─────────────┘
              │
       ┌──────┴──────┐
       │  REMOVED    │
       └─────────────┘

Cross-Referencing Strategy

markdownCopy code
## Cross-Referencing Best Practices

### Types of References

**Related guides**: Links to other how-to guides on related topics
> See also: [How to Configure Authentication](./authentication.md)

**Prerequisites**: Links to content users need before starting
> **Prerequisites**: [Installation Guide](./installation.md), [Account Setup](./account-setup.md)

**Deeper dives**: Links from overviews to detailed content
> For more detail, see [API Reference](../reference/api.md)

**Troubleshooting links**: Connect error messages to solutions
> If you see "Error 403: Forbidden", see [Troubleshooting Access Issues](./troubleshooting.md#403)

### Implementation

```markdown
## Resetting a User Password

> **Prerequisites**:
> - [Admin access setup](./admin-access.md)
> - User's email address or user ID

1. Log into the [Admin Dashboard](https://admin.example.com)
2. Navigate to **Users > Search**
3. Find the user and click **Reset Password**
4. The system sends a password reset email

> **Related**: [Bulk User Management](./bulk-user-management.md) |
> [Troubleshooting: Reset email not received](./troubleshooting.md#reset-email)

Copy code

---

### Contribution Workflows

#### CONTRIBUTING.md for Knowledge Base

```markdown
# Contributing to the Knowledge Base

We welcome contributions from everyone. Here's how to add or improve content.

## Quick Start

1. Fork the knowledge base repository
2. Create a branch: `git checkout -b docs/my-new-guide`
3. Write your content in Markdown
4. Submit a Pull Request

## Content Standards

- **Title**: Clear, question-based or task-based title
- **Description**: One-line summary in frontmatter
- **Tags**: At least 2 tags (content type + topic)
- **Structure**: Prerequisites → Steps → Verification → Troubleshooting
- **Examples**: Include at least one runnable command or code snippet

## Templates

Use the template at `docs/_templates/guide.md` for new guides.

## Review Process

1. **Automated checks**: Markdown linting, link checking, spell check
2. **Peer review**: At least one team member reviews for accuracy
3. **Editorial review**: Content style and structure check (for major additions)
4. **Merge**: Squash and merge to main

## What Gets Accepted

| Type | Accepted? | Review Level |
|------|-----------|-------------|
| New guide | ✅ Yes | Full review |
| Typos/corrections | ✅ Yes | Quick review |
| Code example updates | ✅ Yes | SME review |
| Major rewrites | ✅ Yes | Full review |
| Duplicate content | ❌ No | — |
| Personal opinions | ❌ No | — |
| Outdated information | ⚠️ Requires update | Full review |

Contribution Metrics Dashboard

markdownCopy code
## Contributor Dashboard

| Month | Contributors | New Pages | Updates | Top Contributor |
|-------|-------------|-----------|---------|-----------------|
| Jan 2024 | 12 | 8 | 34 | @alice |
| Feb 2024 | 15 | 6 | 42 | @bob |
| Mar 2024 | 18 | 11 | 55 | @carol |

Analytics and Feedback

User Feedback Widget

markdownCopy code
<!-- Add to every page -->
## Was this page helpful?

- [✅ Yes] [❌ No]

<!-- If No -->
**What could we improve?**
[Free text field]

<!-- Footer -->
Last updated: {{ git_revision_date }}
[Edit this page]({{ edit_url }})

Analytics Tracking

javascriptCopy code
// Docusaurus analytics integration
// docusaurus.config.js
module.exports = {
  themeConfig: {
    // Plausible (privacy-focused analytics)
    plausible: {
      domain: 'docs.myproject.com',
    },
    // Or Google Analytics
    googleAnalytics: {
      trackingID: 'UA-XXXXX-Y',
      anonymizeIP: true,
    },
  },
};

Key Metrics to Track

Knowledge Base Governance

Roles and Responsibilities

Content Review Schedule

yamlCopy code
# Content review cadence by type
review_schedule:
  critical:
    - security procedures: monthly
    - incident response: monthly
    - authentication docs: quarterly
  standard:
    - guides and tutorials: quarterly
    - api reference: with each release
    - faq: semi-annually
  minor:
    - internal procedures: annually
    - project overviews: annually

Common Mistakes

1. Building without a search strategy: A knowledge base with poor search is a graveyard. Invest in search from day one.

2. No content owners: Pages without an owner go stale. Every page should have a clearly documented owner.

3. Too many platforms: Don't split knowledge across Notion, Confluence, and a wiki. Pick one and migrate everything.

4. Over-organizing: Creating too many categories and subcategories buries content. Flat structures with good tags outperform deep hierarchies.

5. Perfectionism over publishing: Docs that are 80% complete and published are infinitely better than perfect docs that never ship.

6. Not tagging content: A well-tagged page is discoverable. An untagged page is lost. Enforce tagging in your workflow.

7. Ignoring stale content: Outdated documentation actively harms trust. Implement automated stale content detection.

8. No contribution guidelines: If people don't know how to contribute, they won't. Make it trivially easy.

9. No feedback loop: Without user feedback, you're writing in the dark. Add a "Was this helpful?" widget on every page.

10. Treating the KB as a side project: Allocate dedicated time for KB maintenance, or it will decay into an abandoned graveyard.

Evaluation Rubric