用途:为技术文档提供分层写作标准,让读者一次读懂。四层各回答一个问题:文档属于哪种类型、句子如何称呼读者、每句承载多少信息、句子是否可能被读成两种意思。四层需同时应用。
主要能力:
- Diátaxis 模式选择。一篇文档只用一种模式:教程(行动+学习)、操作指南(行动+工作)、参考(理解+工作)、解释(理解+学习)。教程以“我们”写命令式步骤,每步有可见结果;操作指南只给步骤、假定读者有能力;参考只描述事实、选项、限制与错误;解释围绕一个真实“为什么”问题,允许观点。不要混用模式,应拆分并链接。
- Google 开发者风格。用“你”和现在时;说明谁做什么;指令写成命令句;条件放在指令前;常见情况在前;标题承载要点而非仅主题;用编号列表表顺序、项目符号表其余;代码用代码字体,UI 元素加粗。
- STE 规则。一句一个指令或一个想法;指令约 20 词、其他句子约 25 词以上应拆分;警告或条件放在被保护的步骤前;保留 the 和 a;每个词一个含义;同一动作固定用同一个词;过程用直接命令,不用被动或叙述;尽量避免 -ing 词。
- Global English。only、not 紧贴所修饰词;拆开长名词串;it、they、this 必须指向明确对象;不省略动词;保留 that 等结构小词;系列中重复冠词;用 both...and、either...or、if...then 消除歧义;用句号而非分号;括号内容须是完整语法单位;不用斜杠;同一事物全文用同一名称;避免习语、拉丁缩写和隐喻。
三条总则:删掉不干活的词;用短小的日常词;规则让句子变差时另想办法或保持原样。代码库就是词表,写真实符号、文件、标志或命令名。不要发明行话。
节奏:有意混合长短句;一句一个想法不等于每句一样长;在允许的模式中给出观点;具体优于空泛。
适用场景:技术文档、PR 描述与提交信息(除 Diátaxis 外各层均适用)。PR 正文应是一分钟可读完的简报,不要粘贴日志、SHA 列表或指标表,改为链接。产品 UI 文案不属于文档,应使用产品自身的文案指南。
限制:资料未提供具体安装命令、平台支持、收费或价格信息。代码片段用制表符缩进,写真实路径与符号,计数或目录树声明须在落地提交时真实,并附上可重新生成的命令。
示例:将冗长的被动配置说明改写为“budget.mjs reads the committed budget from budget.json and counts the files that import protos. If the count exceeds the budget, CI fails. Run budget.mjs --write only to lower the budget.”