| name | technical-writing |
| description | Write clear, engaging technical content from real experience. Use when writing blog posts, documentation, tutorials, or technical articles. |
| category | communication |
| priority | medium |
| tokenEstimate | 800 |
| agents | ["qe-quality-analyzer","qe-api-contract-validator"] |
| implementation_status | optimized |
| optimization_version | 1 |
| last_optimized | 2025-12-03T00:00:00.000Z |
| dependencies | [] |
| quick_reference_card | true |
| tags | ["writing","documentation","communication","blogs","tutorials"] |
Technical Writing
<default_to_action>
When writing technical content:
- LEAD with value (what will reader learn/gain?)
- SHOW, don't tell (specific examples, code, numbers)
- STRUCTURE for scanning (headers, bold, short paragraphs)
- CUT ruthlessly (every sentence must earn its place)
- BE honest about trade-offs
Blog Post Structure:
# Title (specific promise)
## Opening (2-3 paragraphs)
- Hook: The problem or insight
- Context: Why this matters
- Promise: What they'll learn
## Body (3-5 sections)
- One clear idea per section
- Support with examples/code/data
## Closing
- Key takeaway (1-2 sentences)
- Action reader can take
Before/After:
❌ "We implemented a comprehensive testing strategy..."
✅ "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement."
</default_to_action>
Quick Reference Card
Core Principles
| Principle | Bad | Good |
|---|
| Lead with value | "In today's landscape..." | "Here's how we cut bugs 60%" |
| Show, don't tell | "We improved testing" | "Bug detection: 12→47 per sprint" |
| Be specific | "Performance improved" | "Response time: 2.3s→180ms" |
| Honest trade-offs | "This approach is best" | "TDD slowed velocity 20%, reduced bugs 75%" |
Words to Cut
| Kill | Reason |
|---|
| basically, actually, probably | Hedge words |
| leverage, synergy, paradigm | Corporate speak |
| very, really, quite | Unnecessary qualifiers |
| it should be noted that | Just note it |
