technical-writing

# Technical Writing

Write clear technical prose with rigorous quality review.

## When to Use

- Writing technical documentation, design docs, or READMEs
- Drafting blog posts or technical reports
- Writing research papers or whitepapers
- Any technical writing that needs to transfer ideas clearly
- Existing draft needs systematic improvement

**Don't use for**: Quick notes, informal messages, or throwaway text.

## Core Principles

Every sentence serves one goal: **transfer ideas from author to reader**.

1. **Give away the punchline** - State your point upfront, don't bury it
2. **Topic sentences** - First sentence of each paragraph enables scanning
3. **Active voice** - "The system handles X" not "X is handled by the system"
4. **Consistent terminology** - Same concept uses same term throughout
5. **Concrete before abstract** - Examples before generalizations
6. **Figure-first explanations** - Lead with diagrams, standalone captions

## Quality Rubric

Review occurs in three sequential layers. Each layer has specific focus.

### Layer 1: Structure

| Criterion | Requirement |
|-----------|-------------|
| **Main point upfront** | Reader knows the point within first paragraph |
| **Logical flow** | Each section follows naturally from the previous |
| **Section balance** | No section dominates inappropriately |
| **Scannable** | Headers and topic sentences tell the story |
| **Completeness** | No obvious gaps in the argument or explanation |

### Layer 2: Clarity

| Criterion | Requirement |
|-----------|-------------|
| **Active voice** | No passive constructions obscuring agency |
| **Topic sentences** | First sentence of each paragraph states main point |
| **Consistent terminology** | Same concept uses same term throughout |
| **No weasel words** | Avoid "clearly," "obviously," "simply," "just" |
| **Paragraph coherence** | 3-5 sentences, single idea, transition words |
| **Concrete examples** | Abstract claims grounded in specifics |

### Layer 3: Evidence

|