writing-guidelines

writing-guidelines

面向忙碌、不了解你工作内容的读者写作。可读性胜过巧思，清晰胜过面面俱到。

规则

• 先说结果。 第一句话就回答发生了什么或这是什么 - 也就是读者问「长话短说」时想知道的内容。之后再补充细节。
• 删掉填充词。 删除「只是」「简单来说」「基本上」「为了」「值得注意的是」等表达。如果删掉一句话不会改变任何内容，就删掉它。
• 具体胜过抽象。 写明文件、数字和命令。「更快」不如「将构建时间从 40s 缩短到 9s」具体。
• 使用主动语态，每句话表达一个观点。 每句只表达一个要点的短句，比一句包含三个要点的长句更容易快速读懂。
• 术语保持一致。 使用项目自己的词汇，同一事物始终使用同一个词。如果项目有共享语言的 CONTEXT.md，请参照其中的术语（见 domain-modeling）。
• 易读，不要写得生硬。 简短和清晰是两回事。通过删掉读者不需要的内容来精简，而不是把文字压缩成片段、箭头串联（A -> B -> fails）或自造缩写。

错误消息和 UI 文案

• 说明发生了什么，以及下一步该做什么：Config not found at ./app.config.ts. Create it or pass --config <path>. 比 Error: config missing 更好。
• 不要让读者无路可走。每条失败消息都要指出下一步。
• 保持与产品语气一致；删掉感叹号和空洞的热情表达。

应剔除的 AI 腔

• 破折号和短破折号 - 改用前后带空格的连字符或句号。这是最可靠的机器写作特征。
• 空洞的开场白：「在当今快节奏的世界里」「值得注意的是」。
• 层层推测：「也许可能或许」。
• 二元修辞：「不是 X，而是 Y」。
• 能用一句话说明的内容，不要硬拆成结构过度的列表。

输出

编辑时，给出精简后的版本；如果对方提出要求，再为每处修改附上一行说明。不要在修改稿前后添加对原文的赞美。