用途:为技术文档提供分层写作标准,让读者一次读懂。四层各回答一个问题:文档属于哪种类型、句子如何称呼读者、每句承载多少信息、句子是否可能被两种方式解读。
主要能力:
- Diátaxis 模式选择。一篇文档只用一种模式:教程(行动+学习)、操作指南(行动+工作)、参考(理解+工作)、解释(理解+学习)。不混用模式,需要时拆分并链接。
- Google 开发者风格。用“你”和现在时称呼读者,说明谁做什么,指令写成命令句,条件放在指令前,常见情况在前,标题承载要点。
- STE 指令规则。一句一个指令,长指令拆分,警告或条件放在被保护的步骤之前,保留冠词,一词一义,程序写成直接命令。
- Global English 句法。only、not 紧邻所修饰词,拆开长名词串,代词指向明确,不省略动词,用句号而非分号,不用斜杠,同一事物全篇同名。
三条总则:删掉不干活的词;用简短日常词;规则让句子变差时另想办法。代码库就是词表,写真实符号、文件、标志或命令名,不造术语。
使用方式:先按 Diátaxis 选模式,再逐层应用句子规则,最后用检查清单复核。PR 描述和提交信息除 Diátaxis 外适用其余各层。产品 UI 文案不属文档,应遵循产品文案规范。代码片段用制表符缩进,写真实路径与符号,计数或目录树声明须在提交时真实,并附可重新生成的命令。
限制:资料未提供该技能的安装方式、平台支持、收费或价格信息。规则来源为 diataxis.fr、Google 开发者风格、asd-ste100.org 与 Global English 风格指南,具体编号规则与词典在规范 PDF 中。