create-documentation

What this skill does

# Create Documentation

Generate high-quality, reader-centered documentation using Diátaxis framework alignment and cognitive load optimization.

## Purpose

This skill produces documentation that serves readers effectively by:

- **Diátaxis alignment** — Matching content structure to reader intent (learning, doing, understanding, or lookup)
- **Cognitive load management** — Minimizing extraneous load, managing intrinsic complexity, maximizing schema-building
- **Reader persona adaptation** — Tailoring voice, depth, and structure to Anxious Novice, Developer, or Scanning Executive
- **Multi-layer validation** — Verifying structure, content, and reader experience before publication

## When to Use

**Ideal for:**
- User-facing documentation (tutorials, guides, onboarding)
- API and technical reference documentation
- Concept explanations for technical or non-technical audiences
- Feature documentation requiring multiple reader perspectives
- Documentation that must serve readers at different expertise levels

**Avoid when:**
- Internal notes or scratch documentation (no structure needed)
- Highly specialized domain requiring SME validation first
- Legal or compliance documentation (requires legal review)
- Marketing copy (different skill set)
- Documentation requiring real-time data or dynamic content

## Workflow

### Step 1: Document Type Classification

Determine which Diátaxis quadrant fits the reader's needs:

```
Reader's Primary Need → Document Type
─────────────────────────────────────
"Teach me to do X"           → Tutorial
"Help me accomplish Y"       → How-To
"Help me understand Z"       → Explanation
"What are the options for W" → Reference
```

**Decision Tree:**

| Question | Yes Answer | No Answer |
|----------|------------|-----------|
| Is the reader trying to LEARN something? | Continue below | How-To or Reference |
| Is it learning by DOING (practical)? | Tutorial | Explanation |
| Does the reader have a SPECIFIC task? | How-To | N/A |
| Is the reader LOOKING UP information? | Reference | N/A |

**Output:** `doc_type` (tutorial | how_to | explanation | reference)

**Load:** `@references/tutorial-framework.md`, `@references/howto-framework.md`, `@references/explanation-framework.md`, or `@references/reference-framework.md` based on type.

---

### Step 2: Reader Analysis & Confidence Loop

Build a complete reader profile through iterative refinement. Do not proceed until confidence reaches threshold.

**Confidence Loop Logic:**

```
confidence = 0.0
iterations = 0

WHILE confidence < 0.85 AND iterations < 3:

    1. ASSESS what we know about the reader:
       - expertise_level: novice | intermediate | expert
       - persona: Anxious Novice | Developer | Scanning Executive
       - prior_knowledge: What they already know
       - reading_context: Where/how they'll read this
       - success_definition: What "done" looks like for them

    2. IDENTIFY gaps in reader understanding:
       - Unknown expertise level?
       - Unclear persona fit?
       - Missing context about prior knowledge?
       - Undefined success criteria?

    3. RESOLVE gaps:
       IF user available:
           Ask specific clarifying questions
       ELSE:
           Make explicit assumptions with confidence scores
           Document assumptions in output

    4. RECALCULATE confidence based on profile completeness

    iterations++
```

**Reader Dimensions:**

| Dimension | Question | Impact |
|-----------|----------|--------|
| `expertise_level` | How much do they already know? | Vocabulary, depth, assumed knowledge |
| `persona` | What's their emotional/practical state? | Voice, structure, pacing |
| `prior_knowledge` | What specific knowledge do they have? | What to explain vs. assume |
| `reading_context` | How/where will they read? | Length, structure, format |
| `success_definition` | What does success look like for them? | Scope, endpoints |

**Output:** Complete reader profile with confidence >= 0.85

**Load:** `@references/reader-personas.md`

---

### Step 3: Cognitive Load Planning

Design for optimal information absorption given the topic and reader.

**Three-Load Assessment:**

| Load Type | Assessment | Optimization |
|-----------|------------|--------------|
| **Intrinsic** | How complex is this topic inherently? | Sequence, chunk, scaffold |
| **Extraneous** | What presentation overhead can we eliminate? | Remove noise, co-locate info |
| **Germane** | How can we help build lasting understanding? | Examples, connections, reflection |

**Load Strategy by Document Type:**

| Type | Intrinsic | Extraneous | Germane |
|------|-----------|------------|---------|
| Tutorial | Manage carefully | Minimize aggressively | Maximize |
| How-To | Assume away | Eliminate | Optional (via links) |
| Explanation | Embrace complexity | Minimize | Maximize |
| Reference | Minimal per entry | Near zero | N/A |

**Output:** Cognitive load strategy document

**Load:** `@references/cognitive-load.md`

---

### Step 4: Structure Selection

Select and customize document skeleton based on type and reader profile.

**Process:**

1. Load appropriate skeleton from `@templates/document-skeletons.md`
2. Adapt sections based on reader persona:
   - Anxious Novice: Add verification, recovery paths, reassurance
   - Developer: Strip to essentials, ensure copy-paste ready
   - Scanning Executive: Add "why" sections, connections, depth options
3. Plan navigation aids (TOC for >500 words, cross-references)
4. Determine appropriate length based on reading_level:
   - Grade 8: Max 1500 words
   - Grade 12: Max 3000 words
   - Professional: As needed, chunked appropriately

**Output:** Customized document structure/outline

**Load:** `@templates/document-skeletons.md`

---

### Step 5: Content Generation

Write documentation following the selected structure, type-specific patterns, and style guidelines.

**Type-Specific Patterns:**

| Type | Pattern | Key Characteristics |
|------|---------|---------------------|
| Tutorial | Step-by-step learning | Verification after each step, worked examples, recovery paths |
| How-To | Task completion | Imperative verbs, copy-paste ready, minimal context |
| Explanation | Understanding | Multiple perspectives, "why" focus, connections |
| Reference | Information lookup | Consistent entries, complete coverage, self-contained |

**Style Application:**

1. Apply voice appropriate to persona (from `@references/style-guide.md`)
2. Use sentence length appropriate to reading_level
3. Handle technical terminology per audience expertise
4. Format code blocks for copy-paste readiness
5. Use callouts sparingly and purposefully

**Content Quality During Writing:**

- [ ] One concept per sentence/step
- [ ] Active voice preferred
- [ ] Second person for instructions ("you")
- [ ] Terms defined on first use
- [ ] Examples are realistic and minimal

**Output:** Draft documentation

**Load:** `@references/style-guide.md`, appropriate framework reference

---

### Step 6: Multi-Layer Validation

Validate documentation across three layers to ensure quality.

#### Layer A: Meta-Cognitive Self-Audit

Audit your own reasoning and assumptions before validating the document.

**Checklist:**
- [ ] Reasoning chain is traceable (each claim has foundation)
- [ ] Assumptions are inventoried and documented
- [ ] Confidence levels are calibrated appropriately
- [ ] No logical leaps without explanation
- [ ] Document type correctly identified and consistent
- [ ] Structure matches skeleton for this type
- [ ] Title accurately reflects content and type
- [ ] Section flow is logical

**Load:** `@references/self-audit-protocol.md#reasoning-chain-audit`, `@references/self-audit-protocol.md#assumption-inventory`, `@references/checklists.md#layer-a-structural-validation`

#### Layer B: Reader Persona Simulation

Simulate reading the document as each relevant persona.

**For Developer persona:**
- [ ] Scan pattern works (code blocks → headings → bold → prose)
- [ ] Code is copy