technical-writing

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"]
trust_tier	1
validation	{"schema_path":"schemas/output.json"}

Technical Writing

<default_to_action> When writing technical content:

1. LEAD with value (what will reader learn/gain?)
2. SHOW, don't tell (specific examples, code, numbers)
3. STRUCTURE for scanning (headers, bold, short paragraphs)
4. CUT ruthlessly (every sentence must earn its place)
5. 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