writing-documentation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: writing-documentation
description: Produces concise, clear documentation by applying Elements of Style principles. Use when writing or improving any technical documentation (READMEs, guides, API docs, architecture docs). Not for code comments.
---

# Writing Documentation Skill

Apply Strunk & White's *Elements of Style* principles to produce concise, clear technical documentation.

## When to Use This Skill

**Use this skill when:**
- Writing new documentation (README, API docs, guides, tutorials, architecture docs)
- Improving existing documentation
- Reviewing documentation for quality
- User asks to "make this more concise" or "improve clarity"
- User mentions: documentation, docs, README, guide, tutorial, API docs

**Do NOT use this skill for:**
- Code comments (different context, separate skill needed)
- Marketing copy (requires persuasive voice, not neutral clarity)
- Personal blog posts (requires individual voice)

## Workflows

### Workflow 1: Write New Documentation

**Steps:**

1. **Understand the purpose**
   - [ ] What is the primary goal of this documentation?
   - [ ] Who is the target audience?
   - [ ] What do readers need to accomplish after reading?

2. **Load writing principles**
   - [ ] Read `reference/strunk-white-principles.md` to internalize core principles

3. **Determine documentation type**
   - [ ] Read `reference/doc-types.md` to select appropriate type
   - [ ] Identify essential sections based on guidelines

4. **Draft the documentation**
   - [ ] Apply Strunk & White principles while writing

5. **Validate quality**
   - [ ] Run through Quality Checklist (below)
   - [ ] Verify all essential information is present
   - [ ] Confirm document achieves its purpose

### Workflow 2: Improve Existing Documentation

**Steps:**

1. **Read the current documentation**
   - [ ] Understand its purpose and audience
   - [ ] Note specific problems (verbosity, unclear sections, missing info)

2. **Load writing principles**
   - [ ] Read `reference/strunk-white-principles.md`
   - [ ] Review `reference/examples.md` for before/after patterns

3. **Apply improvements**
   - [ ] Remove needless words
   - [ ] Convert passive to active voice
   - [ ] Strengthen vague statements
   - [ ] Eliminate redundancy
   - [ ] Improve organization if needed

4. **Validate improvements**
   - [ ] Run through Quality Checklist
   - [ ] Verify no information was lost
   - [ ] Confirm clarity improved

### Workflow 3: Review Documentation

**Steps:**

1. **Load writing principles**
   - [ ] Read `reference/strunk-white-principles.md`
   - [ ] Review relevant guidelines in `reference/doc-types.md`

2. **Assess against quality criteria**
   - [ ] Run through Quality Checklist (below)
   - [ ] Note specific violations with examples

3. **Provide feedback**
   - [ ] List specific issues found
   - [ ] Reference violated principles
   - [ ] Suggest concrete improvements

## Decision Framework

### When to Write vs Improve

**Write new documentation when:**
- No documentation exists
- Existing documentation is fundamentally wrong or outdated
- Complete restructuring needed (cheaper to rewrite)

**Improve existing documentation when:**
- Core structure and information are sound
- Style or clarity issues can be fixed incrementally
- Specific sections need enhancement

### Choosing Documentation Type

See `reference/doc-types.md` for detailed guidelines. Quick reference:

- **README**: Project overview, quick start, primary entry point
- **API Documentation**: Reference for function/endpoint signatures and behavior
- **Tutorial/Guide**: Step-by-step learning path for accomplishing specific goals
- **Architecture/Design Doc**: Explain system structure, decisions, and tradeoffs
- **CLI Tool Documentation**: Command reference with options and examples

### Prioritizing Conciseness vs Comprehensiveness

**Prioritize conciseness when:**
- Documentation type is reference (README, API docs, CLI docs)
- Readers need to scan quickly
- Ge