用途:为技术文档提供统一写作标准,目标是让读者一次读懂。该标准由四层组成——Diátaxis 结构、Google 开发者风格句式、STE 指令规则、Global English 句法,四层需同时应用。
三条总则位于各层之上:删掉不干活的词(“In order to”改为“to”);用日常短词(use 而非 utilize,help 而非 facilitate,do 而非 perform);当规则反而让句子变糟时,换一种写法或保持原样。术语以代码库为准,写真实的符号、文件、参数或命令名,不臆造行话。
Diátaxis 模式:一个文档只用一个模式,按“行动/理解”与“学习/工作”两个维度选择。行动+学习为教程,行动+工作为操作指南,理解+工作为参考,理解+学习为解释。教程以“我们将构建什么”开头,每步产出可见结果;操作指南只给步骤,假设读者已具备能力;参考只作描述,干燥、完整、无疑;解释围绕真实“为什么”,可有观点。不要混用模式,应拆分并链接。
句法层:以“你”和现在时面向读者,说明谁做什么,指令用命令式,条件放在指令之前,常见情形在前,异常在后。标题承载要点并用句首大写,任务标题用动词短语。链接文字应说明去向,不用“click here”。
STE 层:一句一指令,一句一想法。过长指令拆分。警告或条件放在其守护步骤之前。保留冠词,一个词一个含义,同一动作只用同一个词,过程用直接命令式而非被动或叙述。
Global English 层:only、not 紧邻被修饰词;拆开长名词串;it、they、this 指向明确,必要时重复名词;不省略动词;保留 that 等结构词;用句号而非分号;括号内容须为完整语法单位;不用斜杠;同一事物始终用同一名称。避免习语、俗语与拉丁缩写。
其他:每一份经手文档都要使用 unslop 技能;PR 描述与提交信息适用除 Diátaxis 外的各层;产品 UI 文案不算文档。代码片段用制表符缩进,写真实路径。资料未提供该技能的安装方式、收费、平台与具体使用步骤。