用途:这是一套分层技术写作标准,目标是让疲惫的工程师第一遍就能读懂。四层各回答一个问题:这是什么类型的文档、句子如何称呼读者、每句承载多少信息、句子是否可能被读成两种意思。四层需全部应用。
三条总则:删掉不做事的词("in order to"改为"to");用简短日常词("use"而非"utilize");当规则让句子变差时,换一种写法或保持原样,规则服务于读者。代码库就是词表,写真实的符号、文件、标志或命令名。不要生造术语,用开发者会脱口而出的词。
节奏:有意混合长短句。短句落点,长句承载带条件或后果的事实。一句一个想法不等于一句一个长度。在允许的模式下要有观点,解释类可权衡取舍,参考类保持干燥。要具体而非空洞。
先选模式(Diátaxis):一份文档一种模式。按两个问题选择——内容是指导行动还是理解,服务于学习还是工作。行动+学习为教程,行动+工作为操作指南,理解+工作为参考,理解+学习为解释。教程以"我们"、命令式写作,每步产生可见结果;操作指南假设读者有能力,只讲行动;参考只描述,不指导、不说服、不发表意见;解释围绕一个有边界的主题,允许观点。不要混用模式,应拆分并链接。
面向读者写句(Google 开发者风格):用"你"和现在时;说明谁做什么;指令写成命令;条件放在指令前;常见情况在前;像一位懂行的朋友,不用流行语、比喻,指令中不用"please",程序中不用"simply""easy""quickly";链接文字要说明去向,不用"click here";标题承载要点,用句子式大小写;序列用编号列表,其余用项目符号;代码用代码字体,UI 元素用粗体。
让陈述逐条加载(STE 规则):一句一条指令,其余一句一个想法;指令超过约 20 词、其他句子超过约 25 词就拆分;警告或条件放在所护步骤之前;保留"the"和"a";每个词一个含义一个职责;每个动作固定一个词;程序写成直接命令,不用叙述或被动;尽量避免"-ing"词。
不留两种读法(Global English):"only""not"紧贴所修饰词;拆开长名词串;让每个"it""they""this"指向明确对象,必要时重复名词;不要省略动词;保留显示结构的小词;系列中重复冠词以防误读;说明"and""or"连接哪些部分;用句号而非分号;括号内容要语法完整;不用斜杠;同一事物始终用同一名称;避免习语、口语、拉丁缩写和比喻。
其他:提交信息也属于写作,除 Diátaxis 外各层均适用;产品 UI 文案不属于文档。代码片段用制表符缩进,写真实路径和符号,计数或目录树声明须在提交时属实并附上可重新生成的命令。资料未提供该技能的具体安装方式、收费与平台信息。