write-docs

编写文档

文档是词汇表：它为各个组成部分命名，说明每个部分存在的原因，并传达读者无法通过搜索代码得出的原则。代码是关于当前实际存在内容的唯一事实来源——文档绝不能与代码脱节。写下任何内容之前，先问这个技能所遵循的关键问题：读者能否通过阅读代码，更快、更可靠地获得这些信息？ 如果可以，就指引他们去看代码，而不是把内容抄进文档。

保留与删去

保留——读者无法通过搜索代码得知的内容：

• 原因：某个事物为何存在、划分背后的原则、分类文件名未能揭示的信息。
• 不显而易见的发现：平台特性、“如果移除这个，X 会因为 Y 而出问题”、两个文件默默共享的约定。
• 指向内容所在位置的链接，以及那里存放的是哪类内容和归属规则。

删去——代码或 Git 历史中已有的内容，复制一份只会逐渐过时：

• 具体清单：场景名称、情景表、辅助工具列表、类 ID、文件列表、命令／标志矩阵。
• 叙述和变更日志：“我们将 X 重命名了”“旧的 Y 因为重复而被移除”，以及尝试过但已放弃的做法。
• 具体数量、tick 值、当前常量、行号——任何只是复述代码的内容。

指引，不照抄

当你想列出具体内容时，应指出负责维护它们的文件夹或单个文件，并引导读者前往查看——优先指向文件夹而非文件，优先指向事实来源登记表而非抄录的副本。 描述辅助模块时，应说明其中存放哪类辅助工具，以及内容归属规则，而非列出当前清单。用一个具体例子阐明原则即可；列出完整清单就是警讯。“对阵关系见定义它们的表；ID 根据类登记表确定”在下次编辑后依然成立——而照抄其中任何一项都不会。

每条信息只有一个归属位置

每条信息都必须有且仅有一个权威归属位置；其他文档都应链接到该位置。文档之间重复内容是维护问题——副本会逐渐不一致，读者也无法判断哪个是最新版本。根级／全局文档应包含简短章节，并指向子文档。当两份文档解释同一件事时，应选定一份作为中心文档，并把另一份改为仅提供链接。

链接树形结构，逐级向下

文档应构成一棵从单个根／中心文档即可访问的树：中心文档链接到每份子文档，子文档再链接到其下的模块级文档。导航应向下进行——读者从根文档开始，顺着链接逐级深入，因此整棵树都能从根文档访问。文档只有在复用已归属其他位置的信息时，才应链接回上级文档或横向链接到同级文档——例如，应用文档指向中心文档中的部署章节，而不重复说明；或边界文档注明应参考的同级文档。这正是单一归属规则发挥作用的方式。不要添加没有信息量、只是机械地写一句“属于 X”的反向链接：那是噪声，而且无需这类链接，读者也能从根文档浏览整棵树。

编辑检查

精简现有文档时，看到以下内容就删除：可通过搜索代码发现的项目枚举、变更日志和叙述，以及任何复述代码的句子。然后像没有任何对话背景的陌生读者一样，重新阅读保留下来的内容——每一行都应是原则、原因或指引。如果某一行可以替换成链接，而链接同样准确、同样有用，就直接改为链接。