on-writing-well

清晰的技术文档

何时使用此技能

每当用户要求你编写或编辑文档、说明、README 内容、教程、参考资料、发行说明或其他技术说明性文字时，都使用此技能。

技能说明

每当你编写文档时，都应用以下规则。这些原则以 William Zinsser 的 On Writing Well 为基础。这部作品是清晰、简洁技术写作的可靠指南。运用这些原则，向读者有效地解释技术主题。

一般行为

• 以 William Zinsser 的 On Writing Well 中的原则为基础。这是一部关于如何为读者清晰、简洁地写作的经典作品。
• 默认采用简洁、以读者为中心、注重实践的技术写作风格。
• 目标是向聪明但忙碌的读者清楚地解释技术主题。
• 把读者设想为一位想完成某项任务的特定对象。
• 如果仓库或项目有文档风格指南，应优先遵循。指南未作说明的部分，再应用此技能。
• 如果这些风格规则与用户之后的指示有冲突，应优先遵循用户的明确指示，并在适用时继续采用这些规则。
• 用户要求“编写文档”时，直接提供文档本身，不要描述你的编写过程。

目的与受众

• 开篇明确说明目的：这是什么、面向谁，以及能帮助读者做什么。
• 始终考虑一致的受众群体（例如初学者、中级用户、专家），并据此调整内容深度。
• 聚焦目的；删除或淡化任何无助于读者实现目的的内容。

结构与组织

• 适当时按照“为什么”→“是什么”→“怎么做”的顺序组织内容：
  • 为什么这很重要，或何时使用。
  • 这是什么（概念、组成部分）。
  • 如何使用或操作（步骤、示例）。
• 采用简单、合乎逻辑的结构，并使用清晰、描述性的标题和副标题。
• 将相关信息放在一起；避免将同一概念的说明分散到不同位置。
• 使用列表呈现步骤、顺序和相关项目集合。确保列表项在语法上保持平行。
• 编写操作步骤时，使用编号步骤，并以明确的动作动词开头。

清晰度与风格

• 在准确的前提下，优先使用简短、常见的词语，而不是冗长或抽象的表达。
• 使用具体的语言，避免含糊其辞：说明事物是什么、依赖什么，以及能做什么。
• 每个句子尽量只表达一个主要观点，每段尽量只围绕一个核心思想。
• 默认使用主动语态：“运行命令……”，而不是“应运行命令……”。
• 避免冗赘：
  • 删除“真的”“实际上”“为了”“由于……的事实”等空洞填充语。
  • 在不改变含义的前提下，用更简单的表达替换冗长说法。
• 表达直接、自然：保持专业、平和、自信，避免夸张和俚语。

术语、行话与一致性

• 首次出现新术语或专业术语时，先作介绍，之后保持用法一致。
• 对目标读者来说，精确且通用的技术术语可以使用；避免不必要的行话和缩略语。
• 避免冗长的名词堆叠；将其拆分成更清晰的短语。
• 命令、选项、API 和 UI 标签的命名与格式应保持一致。

示例与说明

• 引入关键概念时，如果示例有助于理解，应附上简短、具体的示例。只有在示例选择取决于缺失的需求时，才询问用户。
• 使用真实、精简的示例，聚焦要说明的概念。
• 对于代码或命令：
  • 可行时，优先提供完整且可运行的代码片段。
  • 只突出相关内容，避免添加分散注意力的细节。
• 按照真实用户操作的顺序，逐步说明复杂流程。
• 明确说明重要约束和边缘情况；不要将它们藏在冗长的段落深处。

改写前 / 后：提升清晰度

改写前：

目前，你可能需要进入设置区域，折腾网络选项来配置系统；这可能会让人困惑，而且比预期花费更长时间。

改写后：

打开 Settings → Network。在 Connection 下，将 Mode 设为 Automatic，然后点击 Save。

读者引导与导航

• 提供导航提示，让读者始终清楚自己所在的位置以及接下来要做什么。
• 在重要章节开头，用一两句话简要说明读者将了解或实现什么。
• 在提供相关操作说明之前，明确说明前置条件（知识、工具、访问权限）。
• 将警告、备注和“易踩坑点”放在相关步骤或概念旁边，不要单独放在相距很远的章节中。
• 在有助于清晰表达时使用“你”：提供说明时直接面向读者。

无障碍与包容性

• 使用描述性标题和有意义的链接文本。
• 为图片提供替代文本，为示意图添加说明。
• 保持句子简短，避免使用习语；优先使用清晰的动词和具体的语言。
• 使用包容、中立的语言，避免带有性别倾向或特定文化背景的示例。
• 如果内容包含屏幕截图，请确保在文本中描述关键信息。

格式约定

• 行内代码和单条命令使用反引号：npm install。

• 示例使用带语言标签的围栏代码块（例如，bash 或 python 围栏代码块）。示例：

  # Install dependencies
  npm install
  

• UI 元素使用粗体（例如，Settings → Update），选项使用 --flag 格式。

• 编号步骤应使用祈使句，并以动作动词开头。

• 示例应简洁，只突出相关内容。

准确性、假设与未知信息

• 准确描述行为、条件和限制。
• 如果用户未提供必要的详细信息，可以：
  • 明确说明合理的假设，或
  • 在任务确实依赖这些信息时，询问缺失的信息。
• 不要编造关于特定系统、API 或环境的不明显事实；如果情况不确定或取决于具体实现，请明确说明。

改写现有文档

• 保留原意和技术准确性；如有不确定之处，在条件允许时向用户或权威来源确认。
• 必须作出假设时，请明确说明并标注为假设。
• 如果审核者或维护者尚不确定，优先进行小幅迭代修改，而不是大幅改写。

国际化

• 使用简短的句子并避免习语，让内容更易于翻译。
• 默认使用 SI 单位，但必要时遵循受众或领域惯例。优先采用明确无歧义的日期 / 时间格式（例如，2026-02-11）。
• 明确说明特定地区的注意事项（日期、货币、键盘快捷键）。

内部修订检查清单

定稿前，请快速对照以下问题检查草稿，并按需修改：

1. 目的与重点

   • 是否在开头附近清楚说明了目的？
   • 每个主要章节是否都服务于该目的？

2. 结构

   • 各章节的顺序是否符合实际用户完成任务的方式？
   • 标题是否具体且信息明确？

3. 清晰度与简洁性

   • 是否存在过长或结构混乱的句子？能否拆分或简化？
   • 是否删除了明显的填充词和重复表达？
   • 每个段落是否都围绕一个明确的观点展开？

4. 技术完整性

   • 关键概念首次出现时是否有定义？
   • 步骤是否完整、顺序正确，并且可以照文执行？
   • 重要限制、边缘情况和故障模式是否都已明确说明？

5. 导航与示例

   • 读者能否通过浏览标题快速找到所需章节？
   • 重要概念和操作流程是否至少有一个有帮助的示例？