Blog

Blog

PHODAL

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

关于我

Github: @phodal     微博:@phodal     知乎:@phodal    

微信公众号(Phodal)

围观我的Github Idea墙, 也许,你会遇到心仪的项目

QQ技术交流群: 321689806
comment

Feeds

RSS / Atom

最近文章

关于作者

Phodal Huang

Engineer, Consultant, Writer, Designer

ThoughtWorks 技术专家

工程师 / 咨询师 / 作家 / 设计学徒

开源深度爱好者

出版有《前端架构:从入门到微前端》、《自己动手设计物联网》、《全栈应用开发:精益实践》

联系我: h@phodal.com

微信公众号: 最新技术分享

标签