writing-documentation

What this skill does

# 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
- Getting started / quick start sections

**Prioritize comprehensiveness when:**
- Documentation type is learning-focused (tutorials, guides)
- Complex concepts require detailed explanation
- Architecture decisions need thorough justification

**Balance both:**
- Use concise overview sections with detailed subsections
- Link to comprehensive resources rather than embedding everything
- Apply progressive disclosure pattern

## Quality Checklist

### Content
- [ ] Purpose is clear
- [ ] Essential information is present
- [ ] No unnecessary information
- [ ] Correct and accurate

### Writing (Core Principles)
- [ ] Active voice predominates
- [ ] Definite statements (not hedging)
- [ ] Positive form
- [ ] Specific, concrete language
- [ ] Concise (no needless words)

### Structure
- [ ] Logical organization
- [ ] Clear headings
- [ ] Scannable
- [ ] Examples where helpful

### Technical Documentation
- [ ] Code examples are executable
- [ ] Commands include full context
- [ ] Prerequisites are stated
- [ ] Error cases are covered

## Reference Files

### When to Load Each Reference

**Load `reference/strunk-white-principles.md`:**
- At the start of EVERY documentation writing/improvement task
- When reviewing documentation

**Load `reference/doc-types.md`:**
- When choosing what type of documentation to write
- When unsure about essential sections for a doc type
- When reviewing documentation structure

**Load `reference/examples.md`:**
- When improving existing documentation (see patterns)
- When you want concrete before/after examples

## Common Pitfalls

**Skipping Principle Loading**: ALWAYS load `reference/strunk-white-principles.md` before writing.

**Following Guidelines Rigidly**: Adapt to the specific project's needs. Some projects don't need all sections; some need additional ones.

**Over-Editing**: "Omit needless words" means remove words that add no value. Keep all information that serves the reader's purpose.

**Sacrificing Accuracy for Brevity**: Accuracy always wins. Express explanations concisely, but never misleadingly.

**Inconsistent Terminology**: Choose one term for each concept and use it consistently.

## Notes

- This skill works iteratively - you can run it multiple times on the same document without degrading quality (idempotent)
- Quality over quantity - a short, clear document is better than a comprehensive, confusing one