technical-document-authoring

技术文档编写

在软件或 Web 工程领域编写或审阅技术文档时，请使用此能力，例如设计文档、RFC、ADR、运行手册、README 或 API 参考。它基于同一套规则提供两种模式：

• 编写 — 起草并重组文档，让读者无需反复阅读就能找到答案。选择一种从结构上就清晰的形式——在第一句话前明确读者、只采用一种文档类型、在开头给出要点——而不是等到后续修改时再补救。
• 审阅 — 阅读草稿，评估它会给读者带来什么负担，并针对具体段落指出每个问题。在两种模式下都坚持同一标准；不能因为草稿是自己写的就放宽标准。

范围仅限读者为团队成员的文档写作技巧——读者包括工程师、审阅者、运维人员，以及任何接手系统的人。受众假设、词汇和示例形式（代码块、终端会话、API 结构）均以此为基础。范围之外包括博客文章、演讲和新闻简报等公开或个人写作；营销文案；小说；软件领域以外的学术论文；以及非软件产品的终端用户文档。

此能力负责文档的简明英语和词汇层面规范（参见 voice-tone-and-maintenance.md）。如果其他相关能力负责某项规则，此能力会按主题提及该规则，而不重复其具体表述。这些移交是有条件的——如果项目未提供相应能力，就直接略过相关移交，并在其位置应用此处的规则：

• 产品需求或规范能力负责规范的章节框架、需求表述和验收标准。此能力负责该框架所规定结构中的句子。
• Agent 技能编写能力负责技能定义及其参考文件中的行文，并在此处规则的基础上补充技能格式规则。
• 对话式报告能力负责聊天轮次、进度说明和完成摘要——也就是回复，而非文档。
• UI 或视觉设计能力负责界面的无障碍性。此能力负责文档的无障碍性。

指南：

• 项目提供了负责某项规则的能力时，必须按主题将规则移交给该能力，并概述其要求，而不是重复其具体表述。
• 如果项目未提供某项移交所依赖的能力，则必须将该移交视为不适用，而不是违规，并在其位置应用此能力自身的规则。

本文档中的关键词“必须”“不得”“必需”“应当”“不应”“建议”“可以”和“可选”，应按照 RFC 2119 中的说明进行解释。

受众和文档类型

请参阅 audience-and-document-types.md，了解以下内容：

• 如何开始编写新文档或重组现有文档
• 如何在起草前确定主要读者及其已有知识
• 如何将文档视为自包含内容——不引用本地文件、进行中的产物或受限访问资源
• 如何预先说明范围、先决条件和明确排除在范围之外的事项
• 如何从四种文档类型（教程、操作指南、参考资料、解释说明）中选择一种，并避免混用
• 如何将常见的软件工程文档形式（RFC、ADR、运行手册、README、API 参考）映射到这四种类型
• “未记录即不存在”规则及其对完整性的影响

结构与流程

关于以下内容，请参阅 structure-and-flow.md：

• 调整章节顺序、撰写或重命名标题、开篇设置先给出答案的章节，或添加预期读者会访问的链接
• 先给出答案、TL;DR 或决策，再提供支持细节
• 在策略和方向文档中说明变更的动机——回答“为什么是现在”、指出利害关系，并将提案定位为候选方案
• 使用读者熟悉的词汇编写便于发现的标题，并根据章节用途选择合适的形式
• 标题层级规则——不得跳过层级；连续标题之间不得缺少介绍文字
• 便于快速浏览——使用描述性标题、段落开头先讲关键概念，并保持段落简短
• 在文档中渐进式呈现信息——概念紧邻相关说明，先易后难
• 使用描述性链接文字和稳定的锚点，方便定位

句子与用词

关于以下内容，请参阅 sentence-and-word-craft.md：

• 从句子层面编辑文档
• 默认使用主动语态、第二人称（“你”）和现在时
• 每句话只表达一个意思，以及如何拆分长句
• 替换较弱的动词（be、have、make），删去填充性短语
• 避免使用以冒号开头的段落标签（The principle:、The rule:），但介绍图表、代码块、列表或表格时除外
• 新术语只定义一次，并始终使用同一术语，不要交替使用同义词
• 谨慎使用缩写（首次出现时写出全称；只有在明显更短且会重复使用时才使用缩写）
• 消除含义模糊的代词（it、this、that、they），改为重复名词或将代词放在指代对象附近

列表、表格和代码示例

关于以下内容，请参阅 lists-tables-and-code.md：

• 何时使用项目符号列表、编号列表、表格或连续行文
• 确保列表各项在语法、大小写和标点上保持一致
• 编号步骤以祈使动词开头
• 用以冒号结尾的引导句引出列表和表格
• 代码示例规则——精简、可运行、贴合实际，并提供上下文
• 行内代码格式、UI 元素格式以及图注和表注
• 使用 Mermaid 编写图表——选择合适的图表类型，将其嵌入 ```mermaid 围栏代码块，并配上标题和文字摘要

语态、语气与维护

关于以下内容，请参阅 voice-tone-and-maintenance.md：

• 采用对话式但专业的语气；不要指责读者
• 使用包容性语言和性别中立的措辞
• 面向全球读者——避免习语、体育或文化隐喻，以及含义不明确的日期格式
• 将常用词汇控制在 CEFR C1 水平（提供按等级划分的替换表，涵盖高于 C2、C2 和 C1 级别的生僻词），让非母语读者无需查词典也能阅读
• 无障碍性——提供替代文本和描述性链接文字，不要只依赖颜色传达信息
• 维护——优先保证内容及时，而非面面俱到；采用 ARID（接受适度重复）；维护单一事实来源
• 自我编辑——多轮修改、大声朗读、复审前稍作休息，并在第二轮修改时删减内容