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

# 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',
    },
  },
};

# 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

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

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

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

---

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

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

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

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

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

# 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']
            });

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

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

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

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

// 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,
    },
  },
};

# 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