README 驱动开发

prtyaa 2023-12-25 13:35:04  63082

分类专栏：资讯

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

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

引子 1：不止自述的 README

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

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

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

一句话简介。这个项目做什么？
项目介绍。它解决了什么问题
特性。包含已完成和待办
使用指南。如何一步步使用这个项目
示例。hello, world 示例
开源协议。

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

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

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

引子 2：产品而非项目

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

电梯演讲 <-> 一句话简介
用户旅程 <-> 项目介绍
竞品分析 <-> 项目对比
用户故事 <-> 待办清单
示例和使用指南 <-> 用户手册
……

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