⚡

编写文档技能Skill writing-documentation

这个技能通过应用《风格的要素》原则，帮助用户编写和改进技术文档，如README、API文档、指南、架构文档等，以提高文档的简洁性、清晰度和可读性。关键词：技术文档、写作技巧、清晰文档、简洁写作、Elements of Style、文档优化、文档审查。

文档编写 0 次安装 0 次浏览 更新于 3/8/2026

name: 编写文档 description: 通过应用《风格的要素》原则，生成简洁、清晰的文档。在编写或改进任何技术文档时使用（README、指南、API 文档、架构文档）。不适用于代码注释。

编写文档技能

应用 Strunk & White 的《风格的要素》原则，以生成简洁、清晰的技术文档。

何时使用此技能

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

  • 编写新文档（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. 提供反馈

    • [ ] 列出发现的具体问题
    • [ ] 引用违反的原则
    • [ ] 建议具体改进

决策框架

何时编写 vs 改进

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

  • 没有文档存在
  • 现有文档从根本上错误或过时
  • 需要完全重构（重写更便宜）

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

  • 核心结构和信息良好
  • 风格或清晰度问题可以逐步修复
  • 特定部分需要增强

选择文档类型

参见 reference/doc-types.md 获取详细指南。快速参考：

  • README：项目概述、快速入门、主要入口点
  • API 文档：函数/端点签名和行为的参考
  • 教程/指南：完成特定目标的逐步学习路径
  • 架构/设计文档：解释系统结构、决策和权衡
  • CLI 工具文档：带选项和示例的命令参考

优先考虑简洁性 vs 全面性

在以下情况下优先考虑简洁性：

  • 文档类型是参考（README、API 文档、CLI 文档）
  • 读者需要快速扫描
  • 入门 / 快速开始部分

在以下情况下优先考虑全面性：

  • 文档类型是学习导向的（教程、指南）
  • 复杂概念需要详细解释
  • 架构决策需要充分论证

平衡两者：

  • 使用简洁的概述部分和详细的小节
  • 链接到全面资源，而不是嵌入所有内容
  • 应用渐进式披露模式

质量检查清单

内容

  • [ ] 目的清晰
  • [ ] 基本信息存在
  • [ ] 没有不必要的信息
  • [ ] 正确且准确

写作（核心原则）

  • [ ] 主动语态主导
  • [ ] 明确陈述（而非含糊）
  • [ ] 积极形式
  • [ ] 具体、具体的语言
  • [ ] 简洁（没有不必要的词语）

结构

  • [ ] 逻辑组织
  • [ ] 清晰的标题
  • [ ] 可扫描
  • [ ] 有帮助的示例

技术文档

  • [ ] 代码示例是可执行的
  • [ ] 命令包含完整上下文
  • [ ] 前提条件已说明
  • [ ] 错误案例已覆盖

参考文件

何时加载每个参考

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

  • 在每个文档编写/改进任务的开始时
  • 当审查文档时

加载 reference/doc-types.md：

  • 当选择要编写的文档类型时
  • 当不确定文档类型的必要部分时
  • 当审查文档结构时

加载 reference/examples.md：

  • 当改进现有文档时（查看模式）
  • 当您想要具体的前后示例时

常见陷阱

跳过原则加载：总是在写作前加载 reference/strunk-white-principles.md。

严格遵循指南：适应特定项目的需求。有些项目不需要所有部分；有些需要额外的部分。

过度编辑：“省略不必要的词语”意味着删除没有添加价值的词语。保留所有服务于读者目的的信息。

为简洁而牺牲准确性：准确性总是优先。简洁地表达解释，但从不误导。

术语不一致：为每个概念选择一个术语并一致使用。

备注

  • 这个技能是迭代工作的 - 您可以在同一文档上多次运行它而不降低质量（幂等的）
  • 质量胜于数量 - 一个简短、清晰的文档比一个全面、混乱的更好