--- name: technical-writing description: "分层的技术写作标准:Diátaxis 结构、Google 开发者风格的句子、STE 指示规则、Global English 句法。用于 /technical-writing,或撰写、评审文档、RFC、readme、PR 描述、commit 消息时。" disable-model-invocation: true --- # 技术写作 写到一个疲倦的工程师第一遍就能看懂。 - 砍掉每个不干活的词。 - 用短的、日常的词:用「用」,不用「利用」。 - 一条规则把句子写差了,就换个办法修这个句子,或随它去。 - 写真实的符号、文件、旗标或命令名,不要同义词,也不要一段对它的描述。 - 不要发明行话。用开发者会大声说出来的词。命名过的模式,第一次出现时就说清它的意思。 ## 变换节奏 - 混合句子长度。把装着两个想法的句子拆开。留着装着一个想法的长句。 - 解释里要有观点。参考保持干。 - 要具体。不要「schema 改动可能引起问题」,要「列重命名会让构建失败」。 ## 先选定模式(Diátaxis) 一份文档,一个模式。不要混模式。拆开,再链接。 - **教程:在做中学。** 说出学习者将要做出什么。每一步都产生一个看得见的结果,并且你要说出他们应该看到什么。解释只给一个从句加一条链接。 - **操作指南:通往一个目标的步骤。** 解决读者的问题。假定对方胜任。只有行动。允许分叉。指南按任务来命名。 - **参考:供查阅的事实。** 只描述。干、完整、确定。镜像被描述之物的结构。 - **解释:理解,以及为什么。** 一个有边界的主题。给出上下文:设计决定、历史、约束、替代方案。观点只允许在这里,别处不行。 ## 把句子写给读者(Google 开发者风格) - 用「你」对读者说话,用现在时。 - 说清谁做什么。只有行动者未知,或无关紧要时,被动才可以。 - 把指示写成命令。条件放在指示前面,常见情形放前面。 - 不要时髦词,不要比喻,不要「请」,规程里绝不要「简单地」「容易」或「很快」。 - 不要预告,也不要让连续的句子以同一个短语开头。 - 链接的文字要说出链接去向哪里。 - 标题承载的是要点,用句子式大小写。每页一个 h1,不要跳级。 - 序列用编号列表,其他用条目。用一个完整的句子引出列表。条目保持平行。 - 代码用代码字体。UI 元素用粗体。列举时保留最后一个逗号。丢掉「等」。 ## 让陈述一次只承载一件事(STE 规则) - 一句一条指示。别处也是一句一个想法。 - 拆开大约超过 20 个词的指示,以及其他大约超过 25 个词的句子。 - 警告或条件放在它所守卫的步骤之前。 - 留着「这个」和「一个」。 - 给每个词一个意思,每个动作选一个词。 - 把规程写成直接命令,绝不要写成旁白,也绝不要用被动。 - 能不用 -ing 形式就不用。 ## 不让句子有两种读法(Global English) - 把「只」和「不」这类词放在它们所改变的那个词旁边。 - 拆开长的名词串。 - 让每个「它」「他们」和「这」指向一个显然的东西。绝不要用「这」或「这会」去指一整句。 - 不要省动词,也不要省掉显示结构的小词,例如那个连接用的「that」。 - 系列里重复冠词,当它能防止误读时。说清「和」或「或」连接的是哪些部分。 - 用句号,不用分号或长破折号。不要斜杠,也不要「(s)」。括号里的文字要是一个完整的语法单位。 - 每个东西到处只用一个名字。 - 跳过习语、口语、拉丁缩写和隐喻。 ## 语气与仓库细节 - 对这个 skill 碰到的每份文档应用 **unslop** skill。那个 skill 拥有注水模式目录:AI 词汇、填充、含糊其辞、格式痕迹。 - PR 描述和 commit 消息也是写作。除了 Diátaxis,每一层都适用于它们。PR 正文是一份简报,评审者不到一分钟就能读完。不要粘贴 swarm 日志、SHA 列表或指标表。链接它们。 - 产品 UI 字符串不是文档。那些用你们产品的文案指南。 - 代码片段用制表符缩进。写真实路径。每个计数或树的断言,在落地它的那个 commit 上为真,并附上重新生成它的命令。