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 | 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 ```markdown ## 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):** ```bash # 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 ``` ```javascript // 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:** ```bash # Install pip install mkdocs mkdocs-material # Create new project mkdocs new . # Serve locally mkdocs serve # Build mkdocs build ``` ```yaml # 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 ```text ┌─────────────┐ │ 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 ```text 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 ```markdown --- 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](relative/path.md) - [Link to reference](relative/path.md) ``` --- ### 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 ```markdown ## 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 ```python # 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 ```markdown ## 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: