technical-writing

技术写作

当交付内容是面向构建者和运营人员的内部技术文档时，使用此技能。

technical-writing 是文档技能簇的核心，适用于：

• 技术规格
• 架构文档
• ADR / 决策记录
• 运行手册和事故处理流程
• 发布 / 回滚 / 迁移指南
• 面向开发者的实现或维护指南

选择模式或确定范围前，请先阅读以下支持文档：

• references/document-modes-and-boundaries.md
• references/mode-structures.md
• references/quality-checklists.md
• references/docs-as-code-and-maintenance.md

何时使用此技能

• 团队需要在开始实现前制定技术规格
• 工程师需要编写架构文档或 ADR，以记录权衡和决策
• 运维人员需要运行手册、回滚指南或事故响应流程
• 迁移或发布需要一份持久的书面流程，其中包含验证和回滚说明
• 面向开发者的内部指南需要说明系统的工作原理，以及如何安全地开展相关工作

何时不使用此技能

• 已发布的 API 文档、SDK 文档、OpenAPI 参考文档、开发者门户内容 → api-documentation
• 发行说明、CHANGELOG.md、面向客户 / 开发者的迁移公告 → changelog-maintenance
• 幻灯片、推介演示文稿、路线图演示、架构演示 → presentation-builder
• 产品定位、发布文案、GTM 信息传达、营销自动化 → marketing-automation
• 主要工作是在编写文档前决定功能或 API 本身 → 先使用 task-planning、api-design 或相关规划技能

说明

第 1 步：确定一种主要模式

起草前，将请求归纳为一种主要模式。

technical_writing_mode:
  primary_mode: spec | architecture | adr | runbook | migration | internal-guide
  audience: engineers | operators | mixed | unknown
  source_of_truth: repo | incident-notes | existing-doc | mixed | unknown
  lifecycle_state: draft | review | rewrite | maintenance
  docs_surface: markdown-repo | docs-site | wiki | unknown
  review_need: decision-signoff | operational-accuracy | handoff-clarity | unknown

每次运行只使用一种主要模式：

• spec → 计划中的变更、目标、约束、设计、发布、回滚、待解决问题
• architecture → 系统结构、边界、接口、权衡、故障模式
• adr → 一项重要决策及其选项和理由
• runbook → 运维、诊断、恢复、升级处理
• migration → 通过验证和回滚，安全地从旧方案迁移到新方案
• internal-guide → 面向维护人员的实现说明

第 2 步：确认受众并排除不属于此范围的内容

写作前回答三个问题：

1. 谁会依据这份文档采取行动？
2. 这份文档应促成什么决策或行动？
3. 哪些相邻技能必须排除在范围之外？

快速分流表：

如果请求听起来像……	使用
发布 API、SDK、webhook 或开发者门户的文档	api-documentation
编写教程、入门指南或 FAQ	由此技能负责，使用终端用户指南模式
总结已发布的变更或维护 CHANGELOG.md	changelog-maintenance
为发布、路线图或架构评审制作幻灯片	presentation-builder
编写发布或产品信息文案	marketing-automation
在编写文档前决定 API 或功能设计	api-design、task-planning 或其他规划技能

第 3 步：收集最低限度的技术依据

不要仅凭感觉起草。先收集最小但可信的一组依据：

• 当前行为或架构说明
• 接口、架构、命令或运维信号
• 发布或运维约束
• 已知故障模式和恢复步骤
• 未解决的问题或权衡

如果缺少依据，请明确标注假设，不要假装文档具有权威性。

第 4 步：选择最精简且合适的结构

使用 references/mode-structures.md，只保留适合所选模式的章节。

第 5 步：遵循各模式的写作规则

• 规格说明必须将目标与非目标分开。
• 架构文档必须说明边界和权衡，而非涵盖每条代码路径。
• ADR必须记录一个决策，而不是写成完整的设计文档。
• 运行手册必须便于在压力下快速采取行动。
• 迁移指南必须优先说明兼容性、验证和回滚。
• 内部指南必须说明实际实现情况，而非面向客户的教育内容或营销卖点。

第 6 步：保持文档即代码友好

默认采用便于审查、适合仓库的写法：

• 稳定的标题
• 使用简洁的项目符号列表，方便操作人员快速浏览
• 明确写出命令、路径、负责人和先决条件
• 为类似 ADR 的文档注明决策日期和状态
• 尽可能链接到事实来源文档，而非重复叙述

第 7 步：进行质量检查

定稿前，请确认：

1. 已明确说明受众，或能清楚判断受众是谁。
2. 文档说明了它要促成的决策或行动。
3. 假设和未知事项均已标注。
4. 在相关情况下，命令、接口、验证、回滚或升级处理步骤具体明确。
5. 没有将相邻的文档技能范围纳入其中。
6. 标题和章节布局符合所选模式。

第 8 步：返回简报或完成的文档

完整起草前，建议使用以下摘要格式：

# Technical Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:

## Source material used
- Repo/docs/evidence:
- Assumptions / gaps:

## Draft structure
1. section
2. section
3. section

## Writing notes
- Key decisions / actions enabled:
- Risks / unknowns:
- Route-outs kept out of scope:

如果用户已要求提供完成的文档，请直接按照上述对应结构输出所选文档。

示例

示例 1：实施前的内部设计文档

输入

编写一份技术规格说明，说明如何将我们的工作队列从 Redis lists 迁移到 Redis streams。工程师需要在编码前了解目标、约束、发布计划和回滚方案。

良好的输出方向

• 模式：spec
• 受众：工程师
• 包含目标、非目标、约束、设计、发布计划、回滚方案和待解决问题
• 不涉及 API 门户发布

示例 2：记录架构决策

输入

我们选择了 Postgres 逻辑复制，而不是双写。请在 ADR 中记录该决策和备选方案。

良好的输出方向

• 记录背景、决策、备选方案、后果和后续事项
• 文档保持简短，聚焦决策

示例 3：事件运行手册

输入

编写一份运行手册，说明当 payments worker 积压激增且重试开始超时时该如何处理。

良好的输出方向

• 模式：runbook
• 包含症状、立即检查、操作步骤、升级处理、回滚／恢复
• 优先考虑操作人员的执行速度，而非散文式解释

示例 4：与 API 文档的边界

输入

更新面向外部开发者的公开 webhook 快速入门和身份验证故障排除页面。

良好的输出方向

• 转交给 api-documentation
• 说明主要工作是发布面向开发者的 API 文档，而非内部技术文档

最佳实践

1. 先选择文档模式，再撰写正文。
2. 让内部技术文档聚焦决策和行动。
3. 只撰写该模式所需的章节；不要强行将每种模板套用于每份文档。
4. 将内部设计／运维文档与 API 门户、用户帮助、发行说明、演示文稿和 GTM 文案区分开。
5. 优先采用文档即代码结构：便于审查的 Markdown、稳定的标题，以及链接到来源的事实。
6. 明确标注假设和未解决的问题。
7. 对于运行手册和迁移指南，让回滚和升级处理步骤易于查找。
8. 如果请求变更了受众，应转交给其他领域，而不是扩展内部文档的范围。

参考资料

• Diátaxis
• Write the Docs — Docs as Code
• Write the Docs — How to write software documentation
• Architectural Decision Records
• Keep a Changelog