README 驱动开发

最近，我又挖了几个开源项目的坑，Ledge、Ledge Framwork、Igso 等等。每次挖新坑的时候，经常性地都要花很多的时间，想着怎么编写 README、完善 README。而就是这么一个简单的 README 的编写，它都要花费我相当长的时间，或是几个小时，或是几天。

问题来了，我真的是在写 README 吗？

引子 1：不止自述的 README

README，又称“自述文件”，是随着软件发布的一种说明文件，里面通常包含有软件的描述或使用的注意事项。

在众多的开源项目里，README 是我们最常修改的文件之一。每当我们添加了一个新的功能，一个新的特性的时候，我们的第一反应就是更新一下 README，以向世人宣告我们的开源产品又添加了新的功能。

所以，在我的那本《GitHub 漫游指南》里，其中有一部分的话题就是关于 README 的编写。对于一个 README 来说，有这么几个关键要素：

一句话简介。这个项目做什么？

项目介绍。它解决了什么问题

特性。包含已完成和待办

使用指南。如何一步步使用这个项目

示例。hello, world 示例

开源协议。

对于某些项目来说，它们还有：

项目对比。如性能、特性等

……

其中的一个主要原因是，在开源领域 GitHub 有比较高的话语权。而 GitHub 使用了 README 作为项目的『首页』，作为了整个开源项目门房。而正是这个首页，让我们重新意识到 README 的重要性，刷新了 README 的作用。

引子 2：产品而非项目

紧接着，在上一篇文章里，我强调了开源产品而非项目。再重新以产品化的维度来考虑 README 的几个要素，我们就有了者的对应关系

电梯演讲 一句话简介

用户旅程 项目介绍

竞品分析 项目对比

用户故事 待办清单

示例和使用指南 用户手册

……

换句话来说，通过编写这个 README 的同时，相当于是一次关于这个开源项目的产品化思考。

README 驱动开发

由于，看不到一个成熟的 RDD 定义，所以我先按我的理解定义出第一个版本的 README 驱动开发：

README 驱动开发是一种通过事先编写 README 的方式，以一步步驱动出受用户欢迎产品的软件开发方法论。它被广泛的应用在开源软件领域，旨在通过从使用者的视角来思考软件的意义和用户体验等。

从这个角度来看的话，在编写 README 的时候，我们要让使用者能：

一眼能理解项目的目的。

快速了解项目的效果。即通过截图或者是线上 DEMO 等方式

迅速地获得反馈。即我只需要执行一个命令，或者是打开网页，就能知道的效果。

知晓他她们的权利与义务。即 LICENSE

……

也就是为什么 README First 在开源领域非常流行的原因。

README First

README First 即通过先编写 README 的方式来：

重新思考项目的价值，而无需真正动手写代码。

吸引更多的潜在用户或者是开发者。

做正确的事情。

构建更好的开发者体验。

它远远要比你做完一个开源项目，再去编写 README 来得快速、可靠。特别是，对于 GitHub 这样的开源平台来说，当别人为你的项目 star 的时候，他/她的 followers 就可以看到这个动态，进一步地提升项目的传播效果，进一步地为你带来更多的 star。

而如果你的项目的 README 不够吸引人的时候，那么你就失去了这种先发优势。

持续更新

它是一份初期的文档，随着项目的进行，越来越多的需求将会由社区反馈过来，文档也会越来越完善。

README 测试

顺便一提，最近我开始在寻找一种新的测试方式，README 测试。

既然一个 README 可以写成结构化的，那么它必然也是可以测试的。它可以是类似于 Gauge、Cucumber 等这样的 BDD 框架，也可以是解析 markdown 后生成的特定的测试用例。

结论

程序员恨别人不写文档，自己恨写文档。

README 就是一个轻量级的文档方案。