writing-documentation

文档编写技能

运用 Strunk & White 的 Elements of Style 原则，编写简洁、清晰的技术文档。

何时使用此技能

在以下情况下使用此技能：

• 编写新文档（README、API 文档、指南、教程、架构文档）
• 改进现有文档
• 审查文档质量
• 用户要求“让内容更简洁”或“提高清晰度”
• 用户提到：文档、docs、README、指南、教程、API 文档

在以下情况下不要使用此技能：

• 代码注释（场景不同，需要单独的技能）
• 营销文案（需要有说服力的语气，而非中立、清晰的表达）
• 个人博客文章（需要体现个人风格）

工作流

工作流 1：编写新文档

步骤：

1. 了解目的

   • 这份文档的主要目标是什么？
   • 目标读者是谁？
   • 读者阅读后需要完成什么？

2. 学习写作原则

   • 阅读 reference/strunk-white-principles.md，掌握核心原则

3. 确定文档类型

   • 阅读 reference/doc-types.md，选择合适的类型
   • 根据指南确定必需章节

4. 起草文档

   • 写作时运用 Strunk & White 原则

5. 验证质量

   • 按照质量检查清单（见下文）逐项检查
   • 确认所有必要信息均已包含
   • 确认文档达成其目的

工作流 2：改进现有文档

步骤：

1. 阅读现有文档

   • 了解其目的和目标读者
   • 记录具体问题（冗长、章节不清晰、信息缺失）

2. 学习写作原则

   • 阅读 reference/strunk-white-principles.md
   • 查看 reference/examples.md，了解修改前后的示例

3. 进行改进

   • 删除不必要的词语
   • 将被动语态改为主动语态
   • 让模糊的表述更加明确
   • 消除冗余
   • 必要时改进组织结构

4. 验证改进效果

   • 按照质量检查清单逐项检查
   • 确认没有遗漏任何信息
   • 确认清晰度有所提升

工作流 3：审查文档

步骤：

1. 学习写作原则

   • 阅读 reference/strunk-white-principles.md
   • 查看 reference/doc-types.md 中的相关指南

2. 依据质量标准进行评估

   • 按照质量检查清单（见下文）逐项检查
   • 记录具体问题及示例

3. 提供反馈

   • 列出发现的具体问题
   • 指明违反的原则
   • 提出切实可行的改进建议

决策框架

何时编写新文档，何时改进现有文档

在以下情况下编写新文档：

• 尚无文档
• 现有文档存在根本性错误或内容过时
• 需要彻底重构（重写成本更低）

在以下情况下改进现有文档：

• 核心结构和信息合理
• 可以逐步解决文风或清晰度问题
• 需要完善特定章节

选择文档类型

详细指南请参阅 reference/doc-types.md。快速参考：

• README：项目概览、快速入门、主要入口
• API 文档：函数或端点签名及行为的参考资料
• 教程/指南：帮助读者实现特定目标的分步学习路径
• 架构/设计文档：说明系统结构、决策和权衡
• CLI 工具文档：包含选项和示例的命令参考

在简洁与全面之间权衡

优先考虑简洁的情况：

• 文档类型为参考文档（README、API 文档、CLI 文档）
• 读者需要快速浏览
• 入门或快速开始部分

优先考虑全面的情况：

• 文档类型侧重学习（教程、指南）
• 复杂概念需要详细说明
• 架构决策需要充分论证

兼顾两者：

• 概览部分简洁，子部分详细
• 链接到全面的资源，而不是把所有内容都写在文档中
• 采用渐进式披露模式

质量检查清单

内容

• 目的明确
• 包含必要信息
• 不含多余信息
• 正确、准确

写作（核心原则）

• 以主动语态为主
• 陈述明确（不含模棱两可的表述）
• 使用肯定表达
• 用词具体明确
• 简洁（不含不必要的词语）

结构

• 组织合理
• 标题清晰
• 便于浏览
• 在有帮助时提供示例

技术文档

• 代码示例可执行
• 命令包含完整上下文
• 说明前置条件
• 涵盖错误情况

参考文件

何时加载各参考文件

加载 reference/strunk-white-principles.md：

• 在每项文档编写或改进任务开始时
• 审阅文档时

加载 reference/doc-types.md：

• 选择要编写的文档类型时
• 不确定某种文档类型应包含哪些必要部分时
• 审阅文档结构时

加载 reference/examples.md：

• 改进现有文档时（参考其中的模式）
• 需要具体的修改前后示例时

常见问题

跳过原则加载：编写前务必加载 reference/strunk-white-principles.md。

僵化遵循指南：根据具体项目的需求调整。有些项目不需要所有章节，有些则需要补充章节。

过度编辑：“删去不必要的词语”是指删除没有价值的词语。保留所有能满足读者目的的信息。

为求简洁而牺牲准确性：准确性始终优先。简洁地解释，但绝不误导。

术语不一致：为每个概念选定一个术语，并始终保持一致。

备注

• 这项技能采用迭代方式，可在同一文档上多次运行而不会降低质量（幂等）
• 重质不重量：简短清晰的文档胜过全面却令人困惑的文档