pstack 拆解 20 · 文体(下):文档标准
正式文档有更高的门槛:一个疲惫的工程师要在第一遍就能看懂。这一篇把它拆成可操作的层。
technical-writing
一篇文档的目标不是"写完",是一个疲惫的工程师在第一遍就能看懂。这句话反过来定义了下面所有具体的写法规则:分层、选模式、写句子、挑词,全都服务于这一个目标。也正是因为这样,当一条规则把某个句子弄得更差时,它的建议是换一种写法,而不是机械照做。
technical-writing 是一套分层的文档标准,用在 docs、RFC、readme、PR 描述、commit message 上。
它分四层,每层回答一个问题:这是什么类型的文档,句子怎么面对读者,每句承载多少,有没有句子能被读出两种意思。四层一起用。
四层之上还有三条总规则。用不上的词全删,"in order to" 就是 "to"。用短而日常的词,"use" 而不是 "utilize"。第三条约重要:当某条规则让一句话变差时,换个写法或者不动它。规则是为读者服务的,一句遵守了所有规则、却读起来像机器写的话,是失败的。
第一层:先选模式(Diátaxis)。 一篇文档只有一种模式。两个问题选出它:内容是在讲行动(doing)还是理解(thinking),是在服务学习还是工作。
- 行动 + 学习 = 教程。你是老师,学习者的成功是你的责任。打开时说的是学习者要做出什么,不是他"将学到"什么。每一步都产出可见的结果,而且尽早、经常。告诉他应该看到什么:期望的输出、提示符的变化、那行日志。解释压到一个从句加一个链接。写成"我们",用命令:"先做 x。现在做 y。"
- 行动 + 工作 = how-to。解决一个人的问题,不是一台机器能执行的操作。假定对方有能力,跳过教学,只讲行动,不留离题、背景和为了完整的完整。用任务给它命名:"如何校准雷达阵列",不是"雷达阵列校准"。
- 理解 + 工作 = 参考。只描述,不指导、不说服、不给观点。干、全、确定。把事实、选项、限制和错误平平地说出来,不 hedge。结构上镜像被描述的东西。尽量从代码生成,好让它保持真实。
- 理解 + 学习 = 解释。一个有边界的话题,可以脱离产品单独读。标题都能承受前面加一个"关于"。锚在一个真实的 why 问题上。给上下文:设计决定、历史、约束、备选。只有在这里,观点是允许的。
不要把模式混起来:教程里不放参考表,参考里不做手把手的教学,how-to 里不辩论。混了就拆开、链接过去。
第二层:把句子写给读者(Google 开发者风格)。 用"你"、现在时。说清谁做什么:"编译器检查",不是"被检查"。指令写成命令:"点击 Submit。" 条件是前置的:"要删除文档,点击 Delete。" 常见情况放前面,例外放后面。不许预告("我们很快会支持……"),不要连续几句用同一个短语开头。链接要说清它通向哪里,永远不要"点这里"。标题要带出观点("先选模式",不是"模式"),用句子大小写。一页一个 h1,不跳级。
第三层:让陈述一次承载一个(STE)。 一条指令一个句子,其他地方一句一个念头。超过约 20 词的指令、超过约 25 词的其他句子,拆开。警告或条件放在它守护的那一步前面。保留"the"和"a":"移除备份文件"能读成两种;加上冠词只读成一种。每个词一个意思、一个职责,然后守住它。一个动作固定一个词:"start",不要这里 start、那里 initiate。流程写成直接命令,永远不写成叙述,也永远不用被动。尽量避开 -ing 词。
第四层:不给句子留下两种读法(全球英语)。 让"only""not"贴着它修饰的那个词。拆开长名词串。每个"it""they""this"都要指向一个明确的东西,拿不准就重复那个名词。不要省动词。保留显示结构的小词,比如"确保那个开关是关的"里的"那个"。in a series 重复冠词以防误读。说清"and""or"连接的是哪些部分。用句号,不用分号。把破折号换成一个新句子。括号里的内容要么是一个完整的语法单位,要么是它自己的句子。不用斜杠。每个东西自始至终一个名字。
它还有一条容易被忽略的:让节奏有变化。 一篇文档可以条条合规,却依然读起来像机器写的,因为每句话都被削得一样短,没有一个观点,没有一处具体。所以句子长短要有意地混合,短句落一个点,长句带一个事实和它的条件;在允许表达观点的模式里(比如解释),要说出你怎么看,而不是只列正反面。
用词上,代码库本身就是词表。写真实的符号、文件、flag、命令名,不要写它的同义词或描述。也不要用生造的术语,用开发者会脱口而出的词。名字不该造:说"move""delete""一个只会变小的预算",不说"evacuate""ratchet""endgame"。
最后一层分工:technical-writing 管文档,PR 描述和 commit message 也是写作,除 Diátaxis 之外每一层都适用;产品 UI 的文案不算文档,用产品自己的文案规范;而且它每碰一处文档,都要再过一遍 unslop。
参考
原文都在 pstack 上游仓库(cursor/plugins):