协作文档

协作文档应让读者无需等待作者在线，就能理解问题、作出判断或继续行动。格式完整本身没有价值。文档应写到什么程度，取决于用途、风险、持续时间和参与者，无法由一套通用模板决定。

本页适用于项目说明、方案、操作说明、研究记录和知识文章。Handbook 本身的写法另见Handbook 编写规范。

先确定读者要完成什么

创建文档前，应先判断它是否比消息或任务描述更适合承载当前信息。内容会被多人或反复使用、需要独立审阅、会影响后续决定，或者口头传递容易失真时，通常值得形成文档。

作者应能够说清楚读者看完后要理解或完成什么。如果文档只是保存作者知道的一切，没有明确读者和用途，增加章节只会提高查找成本。

不同用途需要回答不同问题：

• 方案需要解释要解决的问题、重要约束、建议方向和取舍；
• 操作说明需要说明适用场景、必要前提、如何确认成功以及失败后怎么办；
• 状态说明需要让读者知道什么发生了变化、当前风险和是否需要行动；
• 研究记录需要区分证据、推断、未知问题和已经形成的结论；
• 知识文章需要帮助后来者识别相似问题，单次事件只是用于解释的材料。

这些问题用于判断内容是否充分，无需照抄为标题。

给读者足够而不过量的上下文

文档应包含理解当前内容所需的背景，但可以链接已有权威资料，不必重复整个历史。作者应优先解释那些只有自己知道、读者无法从链接推断的约束和取舍。

信息量应与误解成本相称。一个容易撤销的小改动可以只写结论和理由；影响多个团队、持续数月或难以撤销的方案，需要更完整的背景、替代方向、风险和未决问题。

“更多信息”并不总是更好。与当前判断无关的聊天摘录、重复状态和过早细节会掩盖重点。需要保留的原始材料可以作为附件或研究记录，正文应说明它们如何支持当前结论。

让文档显露自己的状态

读者应能分辨文档是在探索、征求意见、记录当前决定，还是保存历史。状态可以通过标题、开头说明、所在工作流或平台状态表达，不要求统一的 status 字段。

当内容会持续变化、适用范围容易混淆或维护责任不清时，应补充必要说明。稳定概念、一次性提案和有清楚版本历史的记录，不必机械添加 Owner、更新时间和复核日期。

过时内容不能只靠日期判断。旧文档可能仍然正确，新文档也可能已经失效。发现内容不再适用时，应指出当前来源或归档原因，避免后来者把它当作现行事实。

写给真实的人阅读

先让标题和开头帮助读者判断“这是否是我要找的内容”，再展开细节。使用具体名称，解释首次出现的术语，避免依赖内部玩笑、临时代号和只有原团队理解的缩写。

段落、列表、表格和图示应根据内容关系选择。连续论证适合段落，选项比较适合表格，步骤和并列事项适合列表。不要为了“易读”把有因果关系的内容切成互不相连的短句。

截图和视频可以辅助说明界面或过程，但关键前提、结论和例外仍应有文字表达。否则无权访问附件的人、使用搜索的人和 Agent 都无法可靠理解。

链接帮助读者继续走下去

链接不只是参考资料。它应帮助读者找到当前规则、相关决定、实际任务或最终产物。链接文字应说明目标关系，避免使用“这里”“相关资料”等无法脱离上下文理解的名称。

同一内容已有权威来源时，应概括与当前文档有关的部分并链接过去，而不是复制维护。引用外部资料时，应在正文表达自己的判断；外链失效不应使文档失去主要含义。

示例用于展示判断

示例适合展示一条原则如何因场景不同而产生不同写法。好的示例会解释为什么这些信息在当前情境中必要，也会指出哪些内容在更轻量的工作中可以省略。

Agent 和审阅者可以提示读者可能缺少行动所需的上下文、文档状态含糊或信息源冲突，但不能仅凭缺少某个标题或字段断言文档不合格。最终判断应回到读者能否完成这份文档服务的工作。