今天是贝贝报告给你的第 314 天   
2020-01-08 星期三 

今天我给 Tetracamthon 这个项目更新 README 文件，主要是加入了 Motivation 部分。写完觉得哪里不对，可能是在别人的项目里没见过这样写的。我认为有必要整理一下自己对 README 文件的理解。

README 文件一般在项目建立的时候就写，有所谓 RDD (Readme Driven Development) 即 README 驱动开发的做法。按我的理解，这份文件是项目对使用者发出的一个合同邀约，交待清楚总体情况，避免浪费彼此的时间。

既然 README 是承诺，目标就是双向的：我是说给你听的，你要听我说完。这个目标决定了写什么和写多少。

借用 Where, Why, What, Who, When, and How 的框架，README 至少应该回答以下几个问题。

• 它属于什么领域？从大到小怎样细分？有几个分支？在什么位置？
• 为什么要做？必要性在哪里？难点在哪里？为什么有可能成功？
• 它完整是什么？已知数据是什么，限制条件是什么，目标数据是什么？做到什么程度算成功？
• 给谁用？谁应该关心这个？目标用户/假想读者是什么背景？
• 路线图什么样？预期中/实际上在什么时间走到什么位置？
• 怎样使用代码和数据？怎么复现项目成果，怎么调整变量得到自定的结果？

我的项目应该回答 5W1H 的问题，不能一上来就给人家讲个人动机，那是功成名就后接受采访时的话题。