documentation-strategy

これはレビュー時に保存された抜粋です。完全で最新の内容は外部ソースを確認してください。

---
name: documentation-strategy
description: "Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long."
category: process-and-team
catalog_summary: "Documentation systems, what to document, maintenance cadence"
display_order: 2
---

# Documentation Strategy

Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases.

---

## When to use

- Setting up documentation for a new team or product
- Auditing existing documentation
- Fixing stale or scattered docs
- Choosing a documentation tool or platform
- Defining what gets documented and what doesn't
- Establishing maintenance cadence
- Scoping technical writing work
- Designing onboarding documentation (use alongside `team-onboarding-playbook`)

## When NOT to use

- Writing the actual content of a single document (use `content-and-copy`)
- Customer-facing knowledge base copy (use `content-strategy`)
- Code comments and inline documentation (covered by `code-review-web`)
- One-off blog posts or articles (use `content-and-copy`)

---

## Required inputs

- The audience (internal, external, customer, dev, exec)
- Existing docs and their state (where, what shape, last updated)
- Team size and growth trajectory
- The kinds of work that produce documentation (engineering, product, ops, support)
- Tools currently in use

---

## The framework: 4 categories of documentation

Different categories of doc serve different purposes. Conflating them is how docs get bad.

### Category 1: Reference

What things are. Looked up when needed.

Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries.

Properties:
- Comprehensive
- Fact-checked, kept accurate
- Searchable
- Stable structure (links don't break)
- Version-aware where relevant

### Category 2: How-to

How to do specific tasks. Procedural.

Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill."

Properties:
- Step-by-step
- Tested by someone who didn't write it
- Includes the prerequisites
- Includes troubleshooting
- Versioned to the system it documents

### Category 3: Explanation

Why things are the way they are. Conceptual.

Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents.

Properties:
- Narrative
- Captures context (the why)
- Often historical (why we built it this way)
- Links to evidence

### Category 4: Tutorial

Learning-oriented. Walks someone from zero to capable.

Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways.

Properties:
- Sequenced from simple to complex
- Hands-on
- Doesn't assume prior knowledge in scope
- Has clear completion criteria

(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.)

---

## The framework: 5 tiers of doc

Different docs serve different audiences with different stakes.

### Tier 1: Customer-facing

Public docs, customer KBs, API references. High visibility, slow change.

Standards:
- Editorial review
- Version control
- Clear ownership
- High freshness bar
- Tied to release

### Tier 2: Cross-team / shared

Docs used across teams: shared APIs, common services, company-wide processes.

Standards:
- Cross-team ownership clear
- Update obligations on changes
- Mid-to-high freshness bar

### Tier 3: Team-internal

Docs for the team that owns them: how the team works, runbooks, decisions.