qe-technical-writing

技术写作

<default_to_action> 撰写技术内容时：

1. 先突出价值（读者将学到什么、获得什么？）
2. 展示而非空谈（提供具体示例、代码和数字）
3. 便于浏览（使用标题、粗体和短段落）
4. 精简到底（每句话都要有存在的价值）
5. 诚实说明权衡 </default_to_action>

博客文章结构：

# 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

改写前后对比： ❌“我们实施了全面的测试策略……” ✅“我们将探索式测试纳入冲刺规划。现在，QE 会在故事细化期间与开发人员结对。”

快速参考卡

核心原则

原则	不佳示例	优秀示例
先突出价值	“在当今的环境中……”	“我们如何将 Bug 减少了 60%”
展示而非空谈	“我们改进了测试”	“Bug 检出数：每个冲刺从 12 增至 47”
具体明确	“性能提升了”	“响应时间：从 2.3s 降至 180ms”
诚实说明权衡	“这种方法最好”	“TDD 让开发速度降低了 20%，但 Bug 减少了 75%”

应删除的词语

删除	原因
basically、actually、probably	含糊其辞的词语
leverage、synergy、paradigm	企业套话
very、really、quite	不必要的修饰词
it should be noted that	直接说明即可

---

面向不同受众的写作

面向开发人员

• 从代码或具体问题切入
• 展示实现细节
• 讨论权衡与替代方案
• 链接到代码仓库或示例

面向 QA/QE

• 从测试难题切入
• 展示策略，而不仅是工具
• 包含风险评估
• 提供可调整使用的启发式方法

面向管理层

• 开篇说明业务影响
• 使用有意义的指标
• 将技术与成果联系起来
• 精简技术细节

---

编辑检查清单

发布前：

• 标题承诺具体内容
• 开篇能在 30 秒内吸引读者
• 论断有示例支撑
• 已删去所有不必要的词语
• 代码示例已测试且正确
• 核心要点一目了然
• 是否愿意把文章发给尊敬的同事

---

改写示例

改写前： “我们决定实施更全面的测试策略，以便在开发周期的早期发现 Bug。”

改写后： “我们将探索式测试纳入冲刺规划。现在，QE 会在故事细化期间与开发人员结对，在编写代码前识别风险。”

---

改写前： “这种方法有诸多好处，包括提升质量、加快反馈循环以及改善团队协作。”

改写后： “三项成果：平均提前 2 天发现 Bug，回归问题减少 30%，开发人员现在会在设计阶段征求 QE 的意见。”

---

Agent 集成

// 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 协调提示

记忆命名空间

aqe/technical-writing/
├── generated-docs/*   - Auto-generated documentation
├── reviews/*          - Documentation review findings
└── templates/*        - Reusable doc templates

Fleet 协调

const docsFleet = await FleetManager.coordinate({
  strategy: 'documentation',
  agents: [
    'qe-quality-analyzer',         // Generate and review
    'qe-api-contract-validator'    // API doc accuracy
  ],
  topology: 'sequential'
});

---

相关技能

• bug-reporting-excellence - 技术 Bug 写作
• code-review-quality - 评审文档

---

请记住

**写作不是为了给人留下深刻印象。**写作是为了帮助人们解决你已经解决过的问题。做你希望曾经遇到过的那种同事。

**根据经验写作。**只写你在生产环境中做过的事。如果还在探索，请如实说明。