write-docs-cn

写项目文档

先分类，再动笔。 教程和参考是两种东西，混在一起两边都不好用。

类型	目的	组织方式	判断标准
教程	带人走通一次	按顺序，有明确终点	必须能从头读到尾做出结果
参考	查东西	按主题，可随机访问	必须能不读上文直接查到

一份文档同时想做两件事，结果通常是：想学的人被参考细节淹没，想查的人要读一堆铺垫。

判断依据不是标题也不是路径，是读者的使用方式：他是从头读，还是搜进来看一段？

放在哪

规则：每份文档讲清楚自己的主题，子主题只给一句话概括加链接。

具体说：

• 根 README 讲这个项目是什么、怎么跑起来、去哪找别的
• 每个模块的 README 讲这个模块自己的事
• 深入的细节放在它归属的那一层，不要上浮

判断某段内容该放哪：它是谁的细节？ 是某个子模块的实现细节，就放那个子模块的文档里，上层只留一个链接。

这条能挡住 README 无限膨胀。

README 的结构

# 名字

一句话说清这是什么。

## 安装 / 快速开始

最短的可执行路径。

## 用法

最常见的两三个场景。

## 更多

链接到详细文档。

第一屏必须能让人判断「这是不是我要找的东西」，第二屏必须能让人跑起来。

不要在开头放架构介绍、设计理念、技术选型说明。那些放后面或者单独一页。

教程怎么写

• 有明确的终点：读完能做出什么，开头就说
• 每一步可验证：这一步做完应该看到什么，写出来
• 不跳步：作者觉得显然的地方，读者可能卡住
• 前置条件写在最前面：需要装什么、需要什么账号、大概花多久
• 给完整可执行的命令，不给片段

一个检验方法：找个没做过的人照着走一遍。 他卡住的地方就是你跳步的地方。

参考怎么写

• 按可查找性组织，不按叙事顺序
• 每一项独立完整，不依赖上文
• 明确写出默认值、取值范围、错误情况
• 相关项之间给链接

注释和文档的分工

代码能表达的，不要写进文档；文档能表达的，不要写进注释。

注释应该写：

• 非显然的契约（前置条件、后置条件、不变量）
• 为什么这样做（尤其是「为什么不用那个更明显的办法」）
• 外部约束（这个魔数来自某个协议规范）

注释不应该写：

• 复述代码在做什么
• 变更历史（git 里有）
• 实现过程的心路历程

别写「思维链」

一类很常见的坏文字：视角站在「写这段代码的那次会话」，而不是站在「项目现在的状态」。

表现：

• 「以前是……后来改成了……」
• 「这里之前有个 bug，所以……」
• 「见方案 B」（读者不知道方案 B 是什么）
• 「评审时讨论过……」

判断标准：一个刚接触这个项目的人，能不能理解每一个引用、验证每一条说法？ 不能就是这类问题。

改法不是直接删。如果那段话里有事实，先把事实改写成「现在是什么样」，再删掉叙述部分。

保持同步

改了行为就在同一个提交里改文档。 分开做的结果是文档永远落后。

文档里的命令和输出应该定期验证，最好能自动化。过期的文档比没有文档更糟，因为它会让人浪费时间在已经不存在的路径上。

不要做的事

• 不要写「本文档将介绍」这类元叙述
• 不要在 README 开头放大段背景
• 不要把教程和参考混在一页
• 不要写只有作者能看懂的缩写
• 不要留 TODO 而不写清什么条件下会补
• 不要复制粘贴同一段说明到多处（选一个家，其余给链接）