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 就是一个轻量级的文档方案。