technical-writing

# 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:** ```markdown # 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 | --- ## Audience-Specific Writing ### For Developers - Lead with code or concrete problem - Show implementation details - Discuss trade-offs and alternatives - Link to repos or examples ### For QA/QE - Start with testing challenge - Show strategy, not just tools - Include risk assessment - Provide adaptable heuristics ### For Leadership - Open with business impact - Use metrics that matter - Connect technical to outcomes - Keep technical details concise --- ## Editing Checklist Before publishing: - [ ] Title promises something specific - [ ] Opening hooks in 30 seconds - [ ] Claims backed by examples - [ ] All unnecessary words cut - [ ] Code examples tested and correct - [ ] Takeaway crystal clear - [ ] Would send to respected colleague --- ## Example Transformations **Before:** "We decided to implement a more comprehensive testing strategy that would allow us to catch bugs earlier in the development lifecycle." **After:** "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement, identifying risks before code is written." --- **Before:** "The benefits of this approach are numerous and include improved quality, faster feedback loops, and better team collaboration." **After:** "Three outcomes: bugs found 2 days earlier on average, 30% fewer regression issues, and devs now ask QE for input during design." --- ## Agent Integration ```typescript // Generate documentation from code const docs = await Task("Generate Docs", { source: 'src/services/PaymentService.ts', format: 'markdown', includeExamples: true }, "qe-quality-analyzer"); // Review documentation quality const review = await Task("Review Docs", { files: ['README.md', 'docs/api.md'], checkClarity: true, checkCodeExamples: true }, "qe-quality-analyzer"); ``` --- ## Agent Coordination Hints ### Memory Namespace ``` aqe/technical-writing/ ├── generated-docs/* - Auto-generated documentation ├── reviews/* - Documentation review findings └── templates/* - Reusable doc templates ``` ### Fleet Coordination ```typescript const docsFleet = await FleetManager.coordinate({ strategy: 'documentation', agents: [ 'qe-quality-analyzer', // Generate and review 'qe-api-contract-validator' // API doc accuracy ], topology: 'sequential' }); ``` --- ## Related Skills - [bug-reporting-excellence](../bug-reporting-excellence/) - Technical bug writing - [code-review-quality](../code-review-quality/) - Review documentation --- ## Remember **You're not writing to impress.** You're writing to help people solve problems you've already solved. Be the colleague you wish you'd had. **Write from experience.** Only write about what you've done in production. If exploring, say so.