knowledge-base

name	knowledge-base
description	Knowledge Base Creation: Searchable wikis, internal documentation portals, knowledge management systems
metadata	{"author":"cosmicstack-labs","version":"1.0.0","category":"development","tags":["knowledge-base","wiki","internal-docs","knowledge-management","documentation"]}

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

Level	Content	Search	Maintenance	Contribution	Governance
1: Graveyard	Random docs, no structure	None (browse only)	Never updated	No process	No owners
2: Collection	Some structure, inconsistent	Basic text search	Updated reactively	A few contributors	Unclear ownership
3: Organized	Taxonomy defined, templates used	Tagged + full-text search	Regular reviews	Active contributors	Defined content owners
4: Curated	Reviewed content, versioned	Faceted + filtered search	Scheduled audits	Contributor workflows	Editorial board
5: Living	Feedback-driven, analytics-informed	Semantic + AI-assisted	Continuous improvement	Embedded in workflows	Metrics-driven governance

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

---

Actionable Guidance

Platform Selection

Platform	Best For	Key Features	Limitations	Hosting
GitBook	Developer docs, API docs	Git-synced, versioned, search, multi-language	Pricing at scale	Cloud or self-hosted
Notion	Internal wikis, team knowledge	Rich editor, databases, templates, AI search	Export limitations, performance	Cloud only
Docusaurus	Open source project docs	React-based, versioned, MDX, search plugins	Requires developer setup	Static site (any host)
MkDocs	Python projects, simple docs	Python ecosystem, Material theme, plugins	Less flexible than Docusaurus	Static site (any host)
Confluence	Enterprise internal docs	Deep Jira integration, permissions, analytics	Heavy, expensive, poor search	Cloud or self-hosted
Obsidian Publish	Personal knowledge, Zettelkasten	Graph view, backlinks, local-first	Limited collaboration	Cloud (paid)
Outline	Internal wikis (mid-size teams)	Markdown-native, fast, Slack integration	Smaller ecosystem	Cloud or self-hosted

Decision Matrix

## 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):

# 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

// 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:

# Install
pip install mkdocs mkdocs-material

# Create new project
mkdocs new .

# Serve locally
mkdocs serve

# Build
mkdocs build

# 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

                    ┌─────────────┐
                    │  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

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

---
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

Problem	Solution
[Problem description]	[Solution steps]

Related

• Link to related guide
• Link to reference

---

### 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

## 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

# 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

## 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.

#### 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

## 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

# 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

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

---

Cross-Referencing Strategy

## 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)

---

### 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

## 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

<!-- 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

// 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

Metric	What It Tells You	Action When Low
Search success rate	Are people finding what they need?	Improve content, tags, search config
Page views per article	Which content is most/least used?	Promote popular, fix or archive unpopular
Time on page	Are people reading or bouncing?	Improve content quality, add examples
Feedback score	Are users satisfied?	Address negative feedback patterns
Return visits	Is the KB sticky?	Add more cross-references, update content
Contribution rate	Is the community engaged?	Lower barriers, celebrate contributors

---

Knowledge Base Governance

Roles and Responsibilities

Role	Responsibilities	Who
KB Owner	Overall strategy, roadmap, metrics	PM or Tech Lead
Content Stewards	Content quality, templates, style guide	Tech Writer
Subject Matter Experts	Technical accuracy, review, contribution	Engineers
Editors	Review, merge, publishing	Senior contributors
All Contributors	Write, update, fix content	Everyone

Content Review Schedule

# 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

Criterion	1 - Graveyard	2 - Collection	3 - Organized	4 - Curated	5 - Living
Platform	No platform	Basic wiki	Purpose-built KB	Optimized KB	Integrated ecosystem
Structure	No structure	Basic folders	Taxonomy defined	Information architecture	Adaptive, user-validated IA
Search	None	Text search	Tagged + text search	Faceted search	AI-assisted semantic search
Content Freshness	Never updated	Updated reactively	Scheduled reviews	Automated stale detection	Continuous improvement
Contribution	No process	A few contributors	Defined workflow	Contributor program	Embedded in daily workflow
Governance	No ownership	Unclear ownership	Defined roles	Editorial board	Metrics-driven governance
Feedback	None	Occasional	Feedback widget	Analytics-driven	Predictive content recommendations