给下次的自己写一份 README

开头先交代它解决什么问题

一份说明不需要从项目的全部背景写起。先用几句话交代用途、适用范围和入口，让第一次打开目录的人知道自己是否找对了地方。正在使用的状态，也应当与过去的试验区分开。

如果一个目录里同时保留了当前方案和旧材料，可以在开头明确指向当前入口。历史记录保留当时的事实，新的验证结果则应当在当前说明里更新。

启动命令之后，要有验证方法

“运行成功”有时只是指进程没有立刻退出。说明里还需要写下可以观察的结果：应当出现哪个文件、哪个页面能够打开，或者哪条检查能够通过。这样，执行者就不必猜测自己已经做到哪一步。

• 用途：这个目录提供什么能力。
• 前提：运行前需要哪些依赖与配置。
• 开始：当前推荐的入口和最短操作步骤。
• 验证：怎样确认结果完整、行为符合预期。
• 恢复：修改失败时，可以回到哪个状态。

保留会影响判断的限制

只在一台机器上验证过，就把这台机器的条件写出来；没有检查的数据，也应当保持未知。限制写清楚以后，后来的人才能判断自己的环境是否适用，而不会把一个局部结果当作普遍保证。

认证信息不适合出现在普通说明里。可以写清楚它由哪个配置项提供、文件应放在哪里，以及需要什么权限，不必把真实值复制进示例。

在修改发生时顺手更新

等到事情全忘了再补文档，成本总会更高。路径变了，顺手更新路径；入口换了，顺手修改开始步骤；发现恢复说明缺一条前提，就把那条前提补上。

README 不需要复述每一次操作。它负责让人迅速找到现在能用的入口，详细的过程和原始结果可以留在各自的记录里。