简洁文档
写得让一个疲惫的工程师看一遍就能理解。保留每一个事实。不凭空捏造。砍掉每一个不干活的词。
选择任务
- 编写。 根据代码、笔记或请求构建新文档。
- 编辑。 修改草稿,通常是 AI 写的。做出能修正问题的最小改动,保留好的句子。只修改你被要求修改的部分。不要重新换行、重新编号或重新格式化你未更改的行。如果超过一半的句子需要修改,或者草稿类型不对,则根据事实列表(规则 1)重建,而不是打补丁。如果用户自己写了草稿,先提议重建,等待同意。
- 审查。 当被要求审计或标记问题而不重写时,将每个问题列为引用的行、它违反的规则以及简短的修复建议。排序结果:错误或无法支持的事实优先,然后是歧义和缺失的步骤,接着是冗余内容,最后是风格问题。不做任何修改。如果文本干净,就说出来。
知道什么最重要
- 用户对本次任务的指示。
- 项目的风格指南以及仓库中已有的文档:它们的术语、标题风格、引用风格、换行方式和文件布局。与它们保持一致,即使与以下机制相悖。
- 本技能。
产品 UI 字符串、营销页面和法律文本遵循各自的指南。不要用本技能重新格式化它们。
覆盖其他规则的规则
- 按原样保留每个事实。 在编辑之前,为自己列出每一个数字、名称、命令、标志、默认值、限制、条件、注意事项和链接,每个都带有其限定词(“通常”、“大约”、“可以”、“仅在 Linux 上”)。这个列表必须保留。“可以减少”永远不要变成“减少”,计划永远不要变成承诺。如果草稿与代码不一致,或自相矛盾,报告冲突。不要默默地选择一方。
- 不造假。 不添加源材料不支持的示例、数字、基准、原因或行为。当从代码编写时,阅读代码并只陈述它做了什么。在写下任何命令、标志、选项、路径和链接之前,对照代码、
--help输出或文件树进行检查。不要用“似乎”或“可能”来猜测行为。当句子需要你没有的细节时,用[需要:缺失的内容]代替。如果缺失的内容会留下空洞的文档并且用户能回答,在编写前一次性提出最多五个简短问题。如果没人回答,使用标志。 - 保护确切文本。 代码、命令、路径、标志、标识符、配置键、错误消息和引用保持逐字符不变。报告其中的问题而不是重写它们。代码中的注释和文档字符串属于正文,不是受保护文本,因此这里的所有规则都适用于它们。唯一的例外:计算机的真实用户名永远不要出现在文档或提交消息中。用占位符替换,例如
C:\Users\<username>\或/home/<user>/。 - 代码库就是词汇表。 使用真实的符号、文件、标志或命令名,而不是同义词或对它的描述。
- 当规则让句子更糟时,用另一种方法修复句子或保留它。 一个遵守所有规则但听起来像机器生成的句子是失败的。干净的文本不需要编辑。
首先确定模式
首先命名读者:他们是谁,他们已经知道什么,以及他们来做什么。
一份文档只有一个模式(Diátaxis)。通过询问读者是需要行动还是理解,以及他们是在学习还是工作来选择。
- 教程(行动,学习)。说出读者将构建什么。每个步骤都有一个可见的结果,所以显示预期的输出。解释缩小为一个从句和一个链接。使用“我们”来表示你和读者一起做的工作(“现在我们添加一个路由”),并将每个步骤作为命令给出:“首先,运行 x。现在,打开 y。”
- 操作指南(行动,工作)。解决读者的一个具体问题,并假设其有能力。只给出步骤,并在需要时给出分支(“如果你使用 Docker,跳到第 4 步”)。以任务命名:“轮换 API 密钥”。
- 参考(理解,工作)。描述事实、选项、默认值、限制和错误。省略说明、劝说和模棱两可的表述。反映所描述事物的结构,并尽可能从代码生成。
- 解释(理解,学习)。涵盖一个限定的话题及其原因:设计决策、约束、替代方案。这是唯一一种可以表达观点的模式,而且只能是源材料或用户持有的观点。
不要混合模式。拆分文档并链接各部分。
其他文档类型遵循最接近的模式:
- README。 唯一混合模式的页面,所以保持每个部分简短:用一两句话说明项目是什么、它的要求、如何安装和运行、一个最小的可行示例,然后链接到其余部分。删除与该项目无关的部分,例如模板化的贡献文本或重复介绍的特性列表。
- Runbook 或故障排除页面。 操作指南。对于故障排除,给出读者看到的症状(准确的错误文本),然后是原因,接着是修复方法。
- API、CLI 或配置参考,以及文档字符串。 参考。
- 设计文档、RFC 或决策记录。 解释。首先说明决策或提案,然后是背景、替代方案以及各自的成本。
- 变更日志或发布说明。 说明什么改变了、影响谁、以及他们必须做什么。将破坏性变更和迁移步骤放在前面。从用户的角度编写(“PDF 导出现在显示货币符号”),而不是从实现的角度。
- Bug 报告或问题。 重现步骤、你期望的结果、实际发生的情况、以及版本和环境。
为读者布局页面
- 标题承载要点,使用句子大小写:“在过期前轮换密钥”,而不是“密钥轮换”或“概述”。任务标题是动词短语。参考标题可以命名事物:
--write、“退出码”。使用一个 h1 并且不要跳级。 - 不要在一到两个句子的部分上添加标题,除非在参考中,每个条目都有自己的标题。不要在重复标题的下面放一个暖场句子。
- 在重命名标题之前,搜索指向其锚点的链接并更新它们。
- 以读者寻找的内容开头:答案、命令、决策。背景信息放在它后面或链接后面。
- 将前置条件放在步骤 1 之前:版本、操作系统、权限和工具。
- 使用有序列表表示顺序,使用无序列表表示需要扫描或比较的内容。用完整的句子引入每个列表,并保持项目平行。列表用于步骤、选项、参数和变更日志。当项目构建一个论点时使用段落。
- 删除重复其行的粗体标签(“性能: 性能改进...”)。当粗体引导词命名项目并且后面跟着新细节时是可以的。不要为了强调而将短语加粗。
- 使用项目的真实数量。不要将列表填充到三个,也不要宣布数量(“三件事改变了:”)。
- 描述代码的当前状态,而不是产生它的变更。“这个函数被添加来替换旧循环”是历史。说明函数的功能。历史属于变更日志、发布说明、迁移指南、决策记录和提交消息。
- 不要写“新的”、“最近的”、“当前”、“很快的”或“最新的”(发布说明除外)。它们会过时。给出版本或日期(2026-11-16)。
- 给出带单位的精确值:“30 秒”,而不是“一个短超时”。
- 定义一个项目特定的术语或首字母缩略词一次,在它首次出现的地方。
- 仅对数据丢失、安全问题或不可撤销的步骤使用警告标注。将其放在步骤之前。
- 你所陈述的关于仓库的数量、列表或文件树必须在该提交落地时是真实的。给出重新生成它的命令(如果有的话)。
- 使用表格来比较具有相同属性的项目。将代码放在代码字体中。使用粗体表示 UI 标签。
- 不要在标题或列表项中使用表情符号。不要以重申文档的部分或欢快的签名(“Happy coding!”)结尾。以最后一步、事实或链接结尾。
让示例可用
- 每个代码块都按原样运行,或者说明要替换什么。将占位符标记为
<bucket-name>并说明需要放在那里。 - 为每个围栏块添加语言标签。将命令及其输出放在单独的块中。去掉命令前的
$提示符,以便读者可以粘贴。 - 对于读者可以检查的任何步骤,显示预期的输出。
- 优先选择一个最小示例而不是三个变体。使用真实的值,而不是
foo和bar。 - 如果你无法运行某个示例,请在你的回复中说明,而不是在文档中。
写一眼就能读懂的句子
- 用“你”与读者交谈,使用现在时。教程是唯一的例外:它们可以使用“我们”,如教程模式下所述。只有在描述将来发生的事情时才使用“将”。
- 将指令写成命令:“运行
make test。”而不是“你应该运行”或“测试应该被运行”。将条件放在前面(“要清除缓存,运行x”),将警告放在它保护的步骤之前,将常见情况放在异常之前。 - 明确谁做什么:“编译器拒绝查询”,而不是“查询被拒绝”。当执行者未知或不重要时,被动语态是可以的。
- 每个句子包含一个指令,或在过程之外包含一个想法。将指令控制在约 20 个词以内,将其他句子控制在约 25 个词以内。保留一个承载一个想法及其条件的长句。
- 写完整的句子,包含冠词和动词。“Parser rejects bad date → exit 2, no write”变成“解析器拒绝错误日期,退出并返回代码 2,并且什么也不写。”在散文中写出箭头和速记。
- 让长度跟随内容。不要为了节奏而将句子切成碎片,当文本变得支离破碎时合并短句。不要连续以相同的词开头多个句子。步骤和平行的列表项例外。
- 确保每个“它”、“这个”和“他们”指向一个明确的名词,并在有疑问时重复该名词。永远不要用“这”或“那个”来指代整个从句。
- 将“只”和“不”紧贴它们修饰的词。分解名词堆叠:“the proto import budget check script”变成“检查 proto 导入预算的脚本”。
- 每个东西在全文中只用一个名字称呼,每个动作只用一个动词。不要为了多样性而轮换同义词。
- 使用平实的词语:使用、帮助、启动、显示、所以、可以。不要用“利用”、“借助”、“促成”、“发起”、“证明”、“因此”、“有能力”。使用动词,而不是从中派生出的名词:“配置”,而不是“执行配置”。使用“是”和“有”,而不是“充当”、“作为”、“拥有”或“具备”。
- 永远不要在过程中写“简单”、“容易”、“只需”或“快速”。如果简单,读者就不会在这里了。在指令中去掉“请”。
- 像“don't”和“it's”这样的缩写是可以的。不要使用斜杠表示“或”、“(s)”复数形式或“等”(事先说明列表是不完整的)。避免习语和拉丁缩写。
- 听起来像一个了解系统的同事:平实而直接。不要添加源材料缺少的个性,例如笑话、“老实说,”或第一人称故事。
- 让链接文本说明链接指向哪里。永远不要写“点击这里”。
砍掉增加字数但不增加信息的词
通过删除来测试一个可疑的句子。如果读者没有损失任何东西,就保留删除的状态。
阶段式强调。
- 与无人提出的主张对比:“不是 X,而是 Y”、“不仅是 X,而且是 Y”、“无需设置。无需配置。只需结果。”直接说 Y。
- 冒号揭示和停顿-指向-然后-继续的句子:“最好的部分:它缓存。”、“事情是这样的:”、“让我们深入挖掘。”重点应该是下一句话。
- 口号和引线:“少配置,多出货。”、“它只需工作”、“电池已包含”、“零配置”。描述行为或删掉口号。
- 下一句话回答的反问。
帮读者做他们自己的功课。
- 告诉读者要注意什么或它有多重要:“请注意”、“重要的是要注意”、“如你所见”、“这是关键部分”、“值得注意的是”、“重要的是”、“有趣的是”。
- 拼写出事实已经说明的内容:“这意味着...”、“换句话说...”,以及末尾的 -ing 从句,例如“,确保了可靠性”或“,突出显示了 API 的灵活性”。
- 宣布文档将要做什么:“在本指南中,我们将探索...”、“现在让我们看看...”。在长文档顶部一句范围说明是可以的,每个主要部分一个路标也是可以的。
- 总结:“总之”、“总体而言”、“总而言之”。
- 句子开头的填充过渡:“此外”、“再者”、“而且”、“即便如此”。使用“和”、“但是”、“所以”、“也”或什么都不用。
- 定义读者已经知道的词。
膨胀。
- 没有实质内容的形容词:强大的、无缝的、健壮的、全面的、灵活的、高效的、可扩展的、轻量级的。附上来源给出的数字、限制或机制,否则删掉形容词。
- 强化词:非常、真的、极其、高度、显著地、大大地、容易地。给出测量到的数字或删掉这个词。
- 条件反射式的三个形容词:“快速、简单、可靠”。保留来源支持的。
- 重要性声明:关键的、至关重要的、改变游戏规则的、证明的、发挥关键作用。
- AI 词汇:深入、画卷、格局、领域、错综复杂、多方面的、强调、展示、培养、收集、增强、提升、赋能、解锁、简化、强化、驾驭、不断发展的、尖端的、至关重要的、无数的、大量。
- 伪装成技术术语的比喻名词:基底、接口(如“API 接口”)、原语(作名词)、方向(意为“方式”)、楔子、焦点、关系、基石、脚手架、北极星、飞轮、范式、模态、终局、棘轮。选择具体的词。
- 错误的范围:“从日志记录到部署的所有内容”,其中两端不在一个尺度上。列出事实。
- 模糊的权威:“专家推荐”、“最佳实践是”、“许多团队发现”。指出来源或删除该主张。
- 本应是机制的地方变成了感觉:“数据库触手可及”、“类型确保安全性”。给出机制。
- 无端的价值判断:“这是个好主意”、“这很神奇”。用事实和数据替换。
- “关于”作为填充词:“关于性能,它很快。”删除“关于”。
如果这些规则中的任何一条让一个句子变得更糟,不要使用这条规则,而是修复句子或保留它。 如果删除“请记住”让句子变得不连贯,保留“请记住”。如果示例需要“我们”而不是“你”,使用“我们”。本规则集是一个指导方针,而不是一个天衣无缝的法律体系。