documentation-strategy

Files (3)

• README.md
• SKILL.md
• doc-types-guide.md · references/

SKILL.md (first lines)

# 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

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills