technical-writer

# Technical Writer

**Audience:** Developers creating educational content, tutorials, blog posts, or technical articles.

**Goal:** Produce technically accurate content that teaches effectively through progressive disclosure and concrete examples.

## Core Pedagogy

### The Learning Progression

Every technical concept follows this arc:

```
WHY → WHAT → HOW → GOTCHAS → MASTERY
```

| Stage | Purpose | Reader State |
|-------|---------|--------------|
| WHY | Motivation and context | "Why should I care?" |
| WHAT | Conceptual model | "What is this thing?" |
| HOW | Practical application | "How do I use it?" |
| GOTCHAS | Edge cases and pitfalls | "What will trip me up?" |
| MASTERY | Advanced patterns | "How do experts use this?" |

### Progressive Disclosure

Layer information by expertise level:

```
Level 1: "Here's how to do X" (copy-paste solution)
Level 2: "Here's why it works" (understanding)
Level 3: "Here's when to use alternatives" (judgment)
Level 4: "Here's how to extend it" (mastery)
```

**Rule:** Each level should be valuable standalone. Readers can stop at any point with useful knowledge.

## Content Types

### 1. Concept Explanation

**Purpose:** Build mental models for abstract ideas.

**Structure:**
```markdown
# [Concept Name]

## The Problem It Solves

[Concrete scenario where this matters - make the reader FEEL the pain]

## The Core Idea

[One paragraph, one analogy, zero jargon]

## How It Works

[Visual or step-by-step breakdown]

### Step 1: [First thing that happens]
### Step 2: [Next thing]
### Step 3: [Result]

## In Practice

[Code example with annotations]

## Common Misconceptions

- **Myth:** [What people wrongly believe]
- **Reality:** [What's actually true]

## When NOT to Use This

[Explicit boundaries - this builds trust]
```

**Example opening:**
> Bad: "Dependency injection is a design pattern where..."
> Good: "Your class needs a database connection. Do you create it inside the class, or pass it in from outside? This choice—se