Knowledge base & wiki

Wiki from planning to governance (flow)

When standing up a wiki, pick navigation dimensions (role / system boundary / lifecycle) first, then unify template fields and linking rules, and finally wire review and external-link checks into team rituals; align the main sequence with your ceremonies.

  [ Readers & scope: eng / ops / support or split by system domain ]
                    │
                    ▼
              [ Top nav + owner per space ]
                    │
                    ▼
         [ Page template: summary / owner / last_reviewed / tags / related ADR·runbook ]
                    │
                    ▼
              [ Cross-links: canonical page + no long-lived contradictory copies ]
                    │
                    ▼
         [ Search: predictable titles + synonym table + ticket/IM glossary links ]
                    │
                    ▼
              [ Governance: zombie pages / broken links / major process changes must update wiki ]
                    │
                    ▼
           [ Migration: URL map + redirects + search index backfill ]

Information architecture & entry points

Split top navigation by reader role or system boundary; each page opens with two sentences on audience and prerequisites to reduce wrong clicks.

Suggested template fields: summary, owner, related services, keyword tags; titles should stay search-friendly and avoid opaque slang.

Recommended wiki top-level directory structure (reader role + system domain hybrid):

wiki/
└── getting-started/          # New hire entry point
│   └── README.md             # "Start here" main index
│   └── local-setup.md        # Environment setup (→ links to each repo README)
│   └── onboarding-checklist.md
│
└── engineering/              # Developer documentation
│   └── adr/                  # Architecture Decision Records
│   │   └── README.md         # ADR index and format guide
│   │   └── 0042-postgres-events.md
│   └── api/
│   │   └── payment-service-api.md
│   └── guides/
│       └── code-review.md
│       └── release-process.md
│
└── operations/               # Operations documentation
│   └── runbooks/             # Grouped by service
│   │   └── README.md         # Runbook index
│   │   └── payment-svc/
│   │   └── user-svc/
│   └── oncall/               # On-call related
│   │   └── rotation.md       # Rotation schedule
│   │   └── escalation.md     # Escalation path
│   └── postmortems/          # Archived by year/month
│
└── architecture/             # System design
│   └── overview.md           # System overview
│   └── service-dependencies.md
│
└── support/                  # Support team docs
    └── billing-faq.md
    └── customer-escalation.md

Wiki page metadata standard template (required at the top of every page):

---
title: "Database Connection Pool Exhaustion Runbook"
owner: "@sre-team"
last_reviewed: "2024-03-20"
review_cycle: "quarterly"   # monthly / quarterly / annually
status: "active"             # active / outdated / archived
tags: [runbook, database, postgresql, oncall]
related:
  - ../adr/0042-postgres-events.md
  - ../../operations/oncall/escalation.md
audience: "L1 on-call engineers"
prerequisites: "kubectl access to prod cluster"
---

## Overview
(2-3 sentences: what this page solves, target audience, prerequisites)

Search, synonyms, sample tree

Maintain synonyms for informal vs formal names (e.g. “gateway” and “API Gateway” point to the same canonical page); put common team terms in the title or first paragraph so agents and humans search the same way.

Governance, permissions, migration

Governance: periodic zombie-page scans, broken external links, and cross-links from Slack/tickets to canonical articles; major process changes must update the wiki, not only verbal sync.

Content quality standards checklist—good docs vs bad docs:

# Good Docs vs Bad Docs Checklist

## Good documentation has (all must be satisfied):
✓ Opening two sentences clearly state: who the audience is and what problem is solved
✓ Steps are executable: includes commands, expected output, failure handling
✓ Has owner and last_reviewed date
✓ External links are valid (periodically checked)
✓ Has bidirectional links with related docs (what this links to, who links here)
✓ Search-friendly: title contains real user search terms ("db slow" not "DB Performance Issue")

## Bad documentation signs (any one requires revision):
✗ Only a title and "to be filled in"
✗ Steps lack specific commands ("check the config" without details)
✗ last_reviewed more than 180 days ago with no update
✗ External links return 404
✗ Contradicts content on another page (two "authoritative sources")
✗ Title uses internal abbreviations (unclear to outside new hires)

Documentation ownership and maintenance rules:

# Documentation Ownership Rules (institutionalize in team Wiki Guidelines)

## Every page must have an owner
- Owner is responsible for: content accuracy, periodic review, responding to "content error" feedback
- When team member leaves: owner field must be updated in the same PR

## Regular review cycles
| Doc Type | Review Cycle | Events That Trigger Review |
|----------|-------------|--------------------------|
| Runbook | Quarterly | Must review after incidents |
| ADR | 6 months after implementation | Major architecture changes |
| Onboarding docs | Semi-annual | After toolchain changes |
| API docs | On code change | When interfaces change |

## Zombie page detection (CI or periodic script)
# Find pages where last_reviewed is over 180 days old
grep -r "last_reviewed:" wiki/   | awk -F'"' '{print $2, $1}'   | awk '$1 < "'$(date -d '-180 days' +%Y-%m-%d)'"'   | sort

• Permissions: sensitive sections in a separate space, not mixed with public docs.
• Duplication: canonical page + short aliases; no long-lived contradictory copies.
• Migration: URL mapping and redirect lists when switching tools.

SKILL & page metadata template

---
name: knowledge-base-wiki
description: Plan wiki IA and page templates
model: claude-sonnet-4-5
---

# Directory structure principles
structure:
  top_level: [getting-started, engineering, operations, architecture, support]
  owner_per_section: true
  canonical_pages_only: true  # No contradictory copies

# Required page metadata fields
page_metadata:
  required: [title, owner, last_reviewed, status, tags, audience]
  review_cycles:
    runbook: quarterly
    adr: 6months-after-impl
    onboarding: biannual
    api: on-change

# Content quality gates
quality_gates:
  - Opening states audience and problem solved
  - Steps include commands and expected output
  - External links valid (CI check)
  - last_reviewed not more than 180 days old

# Search optimization rules
search_optimization:
  - Title contains real user search terms (common synonyms)
  - tags field contains aliases (e.g. "database" "DB" "postgres")
  - Canonical page for high-frequency terms uses synonym redirects