name: 技术写作 description: “基于真实经验编写清晰、引人入胜的技术内容。用于编写博客文章、文档、教程或技术文章。” category: 沟通 priority: 中等 tokenEstimate: 800 agents: [qe-quality-analyzer, qe-api-contract-validator] implementation_status: 优化 optimization_version: 1.0 last_optimized: 2025-12-03 dependencies: [] quick_reference_card: 是 tags: [写作, 文档, 沟通, 博客, 教程] trust_tier: 1 validation: schema_path: schemas/output.json

技术写作

<default_to_action> 编写技术内容时：

以价值为先导（读者将学到/获得什么？）
展示，而非讲述（具体示例、代码、数字）
为扫描而结构化（标题、加粗、短段落）
无情削减（每个句子都必须有其价值）
诚实对待权衡

博客文章结构：

# 标题（具体承诺）

## 开头（2-3段）
- 钩子：问题或见解
- 背景：为什么这很重要
- 承诺：他们将学到什么

## 主体（3-5部分）
- 每个部分一个清晰的观点
- 用示例/代码/数据支持

## 结尾
- 关键要点（1-2句话）
- 读者可以采取的行动

之前/之后： ❌ “我们实施了全面的测试策略…” ✅ “我们将探索性测试移入冲刺规划。QE现在在故事细化期间与开发人员配对。” </default_to_action>

快速参考卡

核心原则

原则	差	好
以价值为先导	“在当今的格局中…”	“这是我们如何将bug减少60%”
展示，而非讲述	“我们改进了测试”	“bug检测：每个冲刺12→47”
具体化	“性能改进”	“响应时间：2.3秒→180毫秒”
诚实对待权衡	“这种方法最好”	“TDD使速度减慢20%，减少bug75%”

需要削减的词语

删除	原因
基本上、实际上、可能	模糊词语
利用、协同、范式	公司用语
非常、真的、相当	不必要的修饰词
应该注意的是	直接说明即可

针对特定受众的写作

针对开发人员

以代码或具体问题为先导
展示实现细节
讨论权衡和替代方案
链接到仓库或示例

针对QA/QE

从测试挑战开始
展示策略，而不仅仅是工具
包括风险评估
提供可适应的启发式方法

针对领导层

以业务影响开头
使用重要的指标
连接技术到成果
保持技术细节简洁

编辑检查清单

发布前：

[ ] 标题承诺具体内容
[ ] 开头在30秒内吸引注意力
[ ] 主张有示例支持
[ ] 所有不必要的词语已削减
[ ] 代码示例经过测试且正确
[ ] 要点清晰明了
[ ] 愿意发送给尊敬的同事

示例转换

之前： “我们决定实施一个更全面的测试策略，以便在开发生命周期中更早地捕捉bug。”

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

之前： “这种方法的好处很多，包括提高质量、更快的反馈循环和更好的团队协作。”

之后： “三个结果：bug平均提前2天发现，回归问题减少30%，开发人员现在在设计期间征求QE的意见。”

代理集成

// 从代码生成文档
const docs = await Task("生成文档", {
  source: 'src/services/PaymentService.ts',
  format: 'markdown',
  includeExamples: true
}, "qe-quality-analyzer");

// 审查文档质量
const review = await Task("审查文档", {
  files: ['README.md', 'docs/api.md'],
  checkClarity: true,
  checkCodeExamples: true
}, "qe-quality-analyzer");

代理协调提示

内存命名空间

aqe/技术写作/
├── 生成文档/*   - 自动生成的文档
├── 审查/*          - 文档审查发现
└── 模板/*        - 可重复使用的文档模板

车队协调

const docsFleet = await FleetManager.coordinate({
  strategy: '文档',
  agents: [
    'qe-quality-analyzer',         // 生成和审查
    'qe-api-contract-validator'    // API文档准确性
  ],
  topology: '顺序'
});

记住

你不是为了留下深刻印象而写作。 你是为了帮助人们解决你已经解决的问题。成为你希望拥有的同事。

从经验中写作。 只写你在生产环境中做过的事情。如果是探索，请说明。

技术写作Skill technical-writing