Knowledge Base Architect

1. ORGANIZE BY AUDIENCE, NOT BY TEAM
   Bad:  Engineering Wiki > Backend Team > Projects > Auth Service
   Good: Engineering Wiki > Services > Auth Service > [Runbook, API, Architecture]

   Why: People searching do not know which team owns something.
   They know WHAT they are looking for.

2. PROGRESSIVE DISCLOSURE
   Level 1: One-sentence description (search result, page title)
   Level 2: Overview page (what, why, how to get started)
   Level 3: Detailed reference (API docs, config reference)
   Level 4: Deep dives (architecture decisions, postmortems)

3. SINGLE SOURCE OF TRUTH
   Every piece of information should exist in exactly one place.
   Other locations should link to it, not duplicate it.
   Duplication guarantees at least one copy will be outdated.

4. FINDABLE OVER ORGANIZED
   If people cannot find it, it does not exist.
   Invest more in search and cross-linking than in hierarchy.

## Engineering Knowledge Base - Top Level

### Getting Started
- New engineer onboarding guide
- Development environment setup
- Architecture overview
- Key contacts and teams

### Services & Systems
- [Service Name] (one page per service)
  - Overview and purpose
  - Architecture diagram
  - API reference
  - Runbook (operations)
  - On-call guide

### Processes & Playbooks
- Incident response playbook
- Deployment process
- Code review guidelines
- RFC process
- On-call rotation

### Architecture Decisions
- ADR index (numbered, searchable)
- Technology radar
- Approved tools and libraries

### Team Spaces
- [Team Name] (each team gets a space)
  - Team charter and members
  - Current quarter goals
  - Meeting notes (auto-archived)

### Reference
- Glossary of terms
- API standards
- Security policies
- Compliance requirements

# [Service Name]

**Owner**: [Team name]
**On-call**: [Rotation link]
**Repo**: [Link]
**Dashboard**: [Link]
**Last reviewed**: [Date]

## What This Service Does
[2-3 sentences. What problem does it solve? Who uses it?]

## Architecture
[Diagram showing this service in context]
- **Dependencies**: [What this service depends on]
- **Dependents**: [What depends on this service]
- **Data stores**: [Databases, caches, queues]

## API Reference
[Link to auto-generated API docs, or inline reference]

## Runbook

### Common Operations
- How to deploy
- How to rollback
- How to check health
- How to view logs

### Common Issues
| Symptom | Likely Cause | Fix |
|---------|-------------|-----|
| High latency | DB connection pool | Increase pool, check slow queries |
| 500 errors | Downstream timeout | Check [dependency] health |
| Memory spike | Cache miss storm | Restart pod, investigate cache |

### Alerts
| Alert | Severity | Response |
|-------|----------|----------|
| High error rate | P1 | Check logs, identify failing endpoint |
| High latency | P2 | Check dependencies and DB |
| Disk space low | P3 | Run cleanup job, resize if needed |

## Development
- How to run locally
- How to run tests
- Environment variables
- Feature flags

| Feature | Confluence | Notion | GitBook | MkDocs/Docusaurus |
|---------|-----------|--------|---------|-------------------|
| Search | Good | Good | Excellent | Good (with Algolia) |
| API docs | Plugin | Limited | Native | Excellent |
| Version control | Weak | None | Git-based | Git-based |
| WYSIWYG editing | Yes | Yes | Yes | No (Markdown) |
| SSO/SAML | Yes | Yes | Yes | Self-managed |
| Permissions | Granular | Basic | Basic | File-based |
| Templates | Yes | Yes | Limited | Code-based |
| Pricing | $$$ | $$ | $$ | Free (OSS) |
| Best for | Large orgs, existing Atlassian | Small-mid teams, flexible | API docs, public docs | Engineering teams, OSS |

USE CONFLUENCE WHEN:
  - Your org already uses Atlassian (Jira, Bitbucket)
  - You need granular permissions (team spaces, restricted pages)
  - Non-technical stakeholders need to contribute
  - You need structured templates and blueprints

USE NOTION WHEN:
  - Your team values flexibility and aesthetics
  - You need a mix of docs, databases, and project tracking
  - Team is < 100 people
  - You want a single tool for multiple purposes

USE DOCS-AS-CODE (MkDocs, Docusaurus) WHEN:
  - Documentation should live next to code
  - You want version control and PR reviews for docs
  - Engineering team writes most of the content
  - You need to auto-generate API documentation
  - You want full control over structure and deployment

USE GITBOOK WHEN:
  - Primary use case is public-facing documentation
  - You want Git-based workflow with WYSIWYG editor
  - API documentation is a major component
  - You need a polished reading experience

1. TITLES MATTER MOST
   Bad title:  "Q3 Project Update"
   Good title: "Auth Service Migration to OAuth2 - Q3 2025 Update"
   Titles are weighted heavily in search. Be specific and descriptive.

2. USE CONSISTENT TERMINOLOGY
   Pick one term and use it everywhere.
   If you call it "deployment" in one place, do not call it
   "release" or "ship" in another. Create a glossary.

3. ADD METADATA
   Tags: service name, team, technology, document type
   Labels: "runbook", "architecture", "onboarding", "reference"
   Status: "current", "draft", "deprecated"

4. CROSS-LINK AGGRESSIVELY
   Every page should link to related pages.
   "For the deployment process, see [Deployment Guide]."
   "This service depends on [Auth Service]."
   Cross-links help both humans and search engines.

5. WRITE FOR SEARCH
   Include the exact phrases people will search for.
   "How to rotate database credentials" is better than
   "Credential Management Procedures" if that is what people type.

TRACK THESE:
  - Top search queries (what are people looking for?)
  - Zero-result searches (what is missing?)
  - Click-through rate on search results (is the right result appearing?)
  - Search-to-page-view ratio (do people find what they need?)

ACT ON THESE:
  - Top queries with no results → Create that content
  - Queries that lead to wrong pages → Fix titles, add redirects
  - High search volume pages → Keep them updated, add more detail
  - Frequently updated queries → Consider a dashboard instead of a page

CREATION → REVIEW → PUBLISH → MAINTAIN → ARCHIVE → DELETE

CREATION:
  - Use templates for consistency
  - Assign an owner (person, not team)
  - Define the audience and purpose

REVIEW:
  - Technical review for accuracy
  - Editorial review for clarity
  - Stakeholder review if cross-team

PUBLISH:
  - Place in correct location in hierarchy
  - Add tags and metadata
  - Cross-link from related pages
  - Announce if widely relevant

MAINTAIN:
  - Quarterly review by owner
  - Update when referenced systems change
  - Fix broken links
  - Incorporate feedback

ARCHIVE:
  - When content is no longer current
  - Move to archive section (do not delete immediately)
  - Add "ARCHIVED" label with date and reason
  - Redirect old URL if possible

DELETE:
  - After 1 year in archive with no views
  - Or when content is factually wrong and has no historical value

## Content Ownership RACI

| Content Type | Owner | Reviewer | Contributor | Informed |
|-------------|-------|----------|-------------|----------|
| Service docs | Service team lead | On-call engineer | All team members | Dependent teams |
| Onboarding guide | Engineering manager | Recent hire | HR + IT | New hires |
| Architecture decisions | Tech lead | Architects | Engineering team | All engineering |
| Runbooks | On-call lead | SRE team | Service team | All on-call |
| Process docs | Process owner | Management | Practitioners | All engineering |
| Meeting notes | Meeting organizer | N/A | Attendees | Team |

## Documentation Freshness Policy

### Review Cadence by Content Type
| Content Type | Review Frequency | Staleness Threshold |
|-------------|-----------------|-------------------|
| Runbooks | Monthly | 60 days |
| API docs | With each release | 30 days |
| Architecture docs | Quarterly | 180 days |
| Onboarding guides | Quarterly | 90 days |
| Team pages | Monthly | 60 days |
| Meeting notes | Never reviewed | Archive after 90 days |

### Automated Freshness Checks
- Bot scans all pages weekly
- Pages past staleness threshold get flagged
- Owner receives Slack notification
- After 2 weeks unreviewed: page gets "May be outdated" banner
- After 4 weeks: page owner's manager is notified
- Monthly report: % of pages in "fresh" status (target: > 80%)

## Standard Templates

### Available Templates
1. **Service Overview**: For documenting a microservice
2. **Runbook**: For operational procedures
3. **ADR**: For architecture decisions
4. **RFC**: For proposals requiring review
5. **Postmortem**: For incident analysis
6. **Onboarding Guide**: For team-specific onboarding
7. **Meeting Notes**: For recurring meetings
8. **How-To Guide**: For procedural documentation
9. **Reference Page**: For configuration, API, or data reference

### Template Rules
- Every new page MUST start from a template
- Templates include required sections (do not delete them)
- Templates include metadata fields (owner, date, status)
- Template changes require review by knowledge base team

# mkdocs.yml
site_name: Engineering Knowledge Base
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - search.suggest
    - search.highlight
    - content.code.copy
  palette:
    - scheme: default
      primary: indigo

plugins:
  - search:
      lang: en
  - tags
  - git-revision-date-localized:
      enable_creation_date: true
  - redirects:
      redirect_maps:
        'old-page.md': 'new-page.md'

nav:
  - Home: index.md
  - Getting Started:
    - Onboarding: onboarding/index.md
    - Dev Setup: onboarding/dev-setup.md
  - Services:
    - Auth Service: services/auth.md
    - Payment Service: services/payment.md
  - Architecture:
    - ADR Index: architecture/adr-index.md
    - System Overview: architecture/overview.md
  - Runbooks:
    - Incident Response: runbooks/incident-response.md
    - Deployment: runbooks/deployment.md

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true

## Documentation PR Review

[ ] Title is descriptive and specific
[ ] Content is technically accurate
[ ] Links are working and point to the right place
[ ] Code examples are tested and runnable
[ ] Screenshots are current (not showing old UI)
[ ] Metadata is present (owner, date, status)
[ ] Cross-links to related pages are included
[ ] Spelling and grammar are correct
[ ] Template structure is followed
[ ] No sensitive information (secrets, internal URLs for public docs)

MIGRATING FROM WIKI CHAOS TO STRUCTURED KB:

PHASE 1: AUDIT (2 weeks)
  - Export page list with last-modified dates
  - Identify top 100 most-viewed pages
  - Categorize: current, outdated, duplicate, orphaned
  - Survey teams: "What do you search for and not find?"

PHASE 2: STRUCTURE (1 week)
  - Design top-level navigation based on audit findings
  - Create templates for each content type
  - Define ownership model
  - Set up search and tagging

PHASE 3: MIGRATE (4-8 weeks)
  - Start with top 100 most-viewed pages
  - Assign owners and reviewers
  - Update and migrate to new structure
  - Set up redirects from old URLs
  - Do NOT migrate everything (leave old wiki read-only for reference)

PHASE 4: SUSTAIN (Ongoing)
  - Enforce templates for new content
  - Run freshness checks weekly
  - Report on KB health monthly
  - Iterate on structure based on search analytics

STRUCTURE: Organize by audience, not by team. Progressive disclosure.
FINDABILITY: Descriptive titles, consistent terminology, aggressive cross-linking
SEARCH: Track top queries, fix zero-result searches, write for search terms
GOVERNANCE: Owner per page, quarterly reviews, freshness automation
TEMPLATES: Service doc, runbook, ADR, RFC, postmortem, how-to, reference
LIFECYCLE: Create → Review → Publish → Maintain → Archive → Delete
PLATFORM: Confluence (large org), Notion (flexible), docs-as-code (engineering)
METRIC: >80% of pages fresh, zero-result rate < 5%, monthly health report

# Knowledge Base Architect Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]