Documentation Orchestration Patterns

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Good documentation is parallel-friendly.                  │
│   Multiple sections, generated simultaneously.              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Load when: API documentation, code documentation, README generation, architecture docs, user guides Common patterns: Endpoint Discovery, Batch JSDoc Generation, Comprehensive README

Table of Contents

1. API Documentation
2. Code Documentation
3. README Generation
4. Architecture Documentation
5. User Guides

---

API Documentation

Pattern: Endpoint Discovery and Documentation

User Request: "Document all REST API endpoints"

Phase 1: EXPLORE
└─ Explore agent: Find all route definitions

Phase 2: FAN-OUT (Parallel documentation by domain)
├─ Agent A: Document auth endpoints
├─ Agent B: Document user endpoints
├─ Agent C: Document product endpoints
└─ Agent D: Document order endpoints

Phase 3: REDUCE
└─ General-purpose agent: Compile into unified OpenAPI/Swagger spec

Pattern: Interactive Documentation

Phase 1: PIPELINE (Foundation)
├─ Explore agent: Extract all endpoints with types
└─ General-purpose agent: Generate OpenAPI spec

Phase 2: FAN-OUT (Enhancement)
├─ Agent A: Add example requests
├─ Agent B: Add example responses
└─ Agent C: Add authentication examples

Phase 3: PIPELINE
└─ General-purpose agent: Setup Swagger UI / Redoc

---

Code Documentation

Pattern: Batch JSDoc/Docstring Generation

User Request: "Add documentation to the utils module"

Phase 1: EXPLORE
└─ Explore agent: Find all undocumented functions

Phase 2: MAP (Parallel documentation)
├─ Agent A: Document file1.ts functions
├─ Agent B: Document file2.ts functions
└─ Agent C: Document file3.ts functions

Phase 3: PIPELINE
└─ General-purpose agent: Verify consistency, generate type docs

Pattern: Module Overview Generation

Phase 1: EXPLORE
└─ Explore agent: Map module structure, exports, dependencies

Phase 2: PIPELINE
├─ General-purpose agent: Write module overview
├─ General-purpose agent: Document public API
└─ General-purpose agent: Add usage examples

---

README Generation

Pattern: Comprehensive README

User Request: "Create a README for this project"

Phase 1: FAN-OUT (Parallel information gathering)
├─ Explore agent: Project structure and technologies
├─ Explore agent: Build and run scripts (package.json, Makefile)
├─ Explore agent: Environment variables and config
├─ Explore agent: Test setup and commands
└─ Explore agent: Existing docs and comments

Phase 2: REDUCE
└─ General-purpose agent: Synthesize into structured README

Sections:
- Overview and purpose
- Quick start
- Installation
- Configuration
- Usage examples
- Development setup
- Testing
- Contributing

---

Architecture Documentation

Pattern: C4 Model Documentation

User Request: "Document the system architecture"

Phase 1: FAN-OUT (Parallel level documentation)
├─ Agent A: Context diagram (system + external actors)
├─ Agent B: Container diagram (applications, data stores)
├─ Agent C: Component diagram (internal components)
└─ Agent D: Code diagram (critical classes/modules)

Phase 2: REDUCE
└─ General-purpose agent: Compile into architecture doc with diagrams

Pattern: Decision Record Generation

Phase 1: EXPLORE
└─ Explore agent: Find architectural patterns in code

Phase 2: FAN-OUT
├─ Agent A: Document decision 1 (why this database?)
├─ Agent B: Document decision 2 (why this framework?)
└─ Agent C: Document decision 3 (why this structure?)

Each ADR includes:
- Context
- Decision
- Consequences
- Alternatives considered

---

User Guides

Pattern: Feature-Based Guides

User Request: "Write user documentation for the dashboard"

Phase 1: EXPLORE
└─ Explore agent: Map dashboard features and capabilities

Phase 2: FAN-OUT (Parallel feature guides)
├─ Agent A: Guide for feature 1 (with screenshots)
├─ Agent B: Guide for feature 2
├─ Agent C: Guide for feature 3
└─ Agent D: Troubleshooting guide

Phase 3: REDUCE
└─ General-purpose agent: Compile into user manual with TOC

---

Task Management for Documentation

Structure documentation work with parallel generation:

# Create documentation tasks
npx cc-mirror tasks create --subject "Audit existing docs" --description "Review current documentation state..."
npx cc-mirror tasks create --subject "Document API endpoints" --description "REST API documentation..."
npx cc-mirror tasks create --subject "Document components" --description "React component docs..."
npx cc-mirror tasks create --subject "Document utilities" --description "Helper function docs..."
npx cc-mirror tasks create --subject "Review consistency" --description "Ensure consistent style..."
npx cc-mirror tasks create --subject "Verify examples" --description "Test all code examples..."

# Parallel doc generation after audit
npx cc-mirror tasks update 2 --add-blocked-by 1
npx cc-mirror tasks update 3 --add-blocked-by 1
npx cc-mirror tasks update 4 --add-blocked-by 1
npx cc-mirror tasks update 5 --add-blocked-by 2,3,4
npx cc-mirror tasks update 6 --add-blocked-by 5

# Spawn parallel documentation agents (sonnet for well-structured work)
Task(subagent_type="general-purpose", prompt="Task 2: Document API endpoints...",
     model="sonnet", run_in_background=True)
Task(subagent_type="general-purpose", prompt="Task 3: Document components...",
     model="sonnet", run_in_background=True)
Task(subagent_type="general-purpose", prompt="Task 4: Document utilities...",
     model="sonnet", run_in_background=True)

Output Formats

| Doc Type | Format | Tool | | ------------ | ------------------- | ---------------------- | | API docs | OpenAPI/Swagger | YAML/JSON | | Code docs | JSDoc/docstrings | Inline | | READMEs | Markdown | .md files | | Architecture | Markdown + diagrams | Mermaid/PlantUML | | User guides | Markdown/HTML | Static site generators |

---

─── ◈ Documentation ─────────────────────