如何编写好的 README 之最佳实践

发布于 2022-05-04 13:04:13 字数 12526 浏览 1426 评论 0

文章总结了为何要编写 README 的动机，给出了一个最简 README 的组成。文末还会给出一个完全的 README 可遵循的套路/模板，但作者更推荐以最简的风格编写你的 README。

为什么你应该编写 README？打个比方，你的代码/产品就像厨房里许多上佳的食材，而一份好的 README 则像一份菜谱。没有菜谱，再好的厨师也有可能不知道如何使用这些食材，更不可能用它们创造出一份美食。

Tom Preston Werner 在 README Driven Development（读我驱动开发）中表达了这种观点：开发一个模块时，你应该想清楚你希望最后在“如何使用”一节展示给读者什么样的 API，写成 README，以此作为验收标准来开发你的模块。这和 TDD 的思想有相似之处：从使用者的角度考虑 API 要做成什么样。

大家为什么会看你的 README？因为想快速地知道这个仓库 适不适用 以及（若适用）应该怎么用。好的 README 必须在最短时间内回答这两个问题（若你愿意为别人节省时间）。由此，引出了一份好的 README 应包含的一个最小骨架：描述、安装与 Demo。

README 的读者是谁

未来的自己
用户
贡献者
项目同事、协作者

最佳实践之最简 README

简洁即美。一份 README 的功能，回答了适不适用及如何使用这两个问题就极好，以易于理解的方式回答则加分，不会再多了。其余必要但无关的信息（如 Issue Tracker、Contribution、License 等）应该以链接文件的形式给出，读者自愿阅读，不应主动占据读者的阅读精力和时间。总述起来，一份 README 的三要素包括：描述、安装、demo。下面简要介绍。

描述

一段仓库的描述，必须简短。它要帮读者回答适不适用这个问题，最好能为读者提供决策依据，比如：

仓库解决了什么问题
仓库以什么方式更好/更优雅/更快地解决了问题
同质产品的关键指标对比
给出简要的决策依据：什么时候很适用，什么时候绝不适用

这一步，产品的 logo/gif 或精心选择的 badges 都是加分项。有了更易看，说白了更容易吸引点赞，但对关键信息的释出贡献甚微。

安装与 Demo

如果读完了描述，读者觉得这个仓库适用，或者读者决定试用一下，那么就来到了安装部分。这个部分的任务，便是告诉读者如何安装你的仓库。这方面 node 的模块特别有优势，只需要一行 npm install 通常就可以完成安装了，这也是对使用者非常友好的。

Demo 部分则需要告诉读者，如何使用你的模块。常见的代码片段 code snippet 绝对必要，毕竟 code talks。好的代码片段，读者自己就可以推断出很多使用信息，比如函数参数个数、类型、值范围、promise 还是回调等信息。

另外，如果有其他传递效率更高的媒介，比如一个简短的视频、GIF 图展示了项目如何使用、常见 API 和使用场景、运行起来是什么样等，则对于读者更加直观、省时。

下面是一个例子，它完整包含了最小核心内容的三部分：描述（以动图）、安装、demo。

Licenses

营业执照。最好要有（没有的话，除了 Github 的 Terms of Service 外默认其他用户不具备任何权限，包括阅读、修改、复制等），并且放置在单独的 LICENSE 文件中。如何选择一个 License，不同 License 的区别是什么呢？见下面几图。

MIT:

GPL GNU General Public License V2:

Apache License V2.0:

完整套路 - README 的完整结构

前面提到，README 最好也能遵循一定的结构组织。精心组织的结构符合认知规律和次序，一致，具备可预测性，读者可以大概预测到需要的信息可以在哪个小节看到。这里有一份大致的套路，以一定的认知规律来组织这诸多信息：

介绍 Introduction：这是一个什么工具/仓库，有什么特色和长处，为什么要用它。必须有一段简明描述，需要额外解释则另起一段进行长解释
目录 Table of Contents：助于快速浏览
安装/构建与环境要求 Installation/Build & Environment Requisitions：快速安装是上手的第一步，极重要。若有特别的环境要求，简要点明又节省了使用者的时间，功德无量
简易例子 Examples / Demos / Getting Started：快速上手的第二步，提供一些即抄即用的例子代码，最好与环境低相关、包含80%的常用场景，极重要
常见事项 Common Pitfalls：安装或 demo 过程常出错的配置或环境疑问，给予统一回答。如果是频繁更新的库，最好还要有升级提示和兼容性建议
API 与文档 API Documentations：更详尽的例子、特性与高级用法。也可以给出一个链接或网址
社区支持 Known Bugs / Issues / Community Supports：如何查找已知 issues/bugs、出了问题去哪寻求帮助。简要地放个链接
如何贡献 Contributing：包含代码库、故事墙、邮件组、CI/CD、代码风格等贡献代码的要求。建议放在单独的 DEVELOPMENT 文件中
LICENSES：版权所有。蛮重要，建议放在独立的 LICENSE 文件中

README 大乱评

看完上面的最小内容核心，及完整的 README 结构，结合度过的一些文章和 README，我认为好的 README 应该具备以下要素，重要性依次递减：

最小核心内容（MKC, Minimum Kernel Content）：描述、安装、demo
图片：图片有时能更简单地表达事物关系，动图则能简要演示代码运行效果
风格：在必有的内容之外，遣词用句选图，可发挥的部分则显明了风格，是作者的标识
样式：好的 UI 也是加分项，但仅加分
结构：README 也以符合一定结构规范为好，减少读者的认知成本。规范哪里来？见下节

下面是一些 README 评测及简要点评：

Repo	最小核心内容	图片	风格	样式	结构
pageres	√√√√√	-	√	√√√	√√√√
bluebird	√√	-	√√	√√	√√√
httpie	√√√√	√√√	√	√√√	√√√√√
joe	√√√√√	√√√√√	√√√√	√√√√	√√√√
hicat	√√√√√	√√√√√	√√√	√√√	√√√√
github-changelog-generator	√√√√	√	√√	√√	√√√√√
enhancd	√√√	√√√√√	√√	√√√√√	√√√
gaze	√√√√	-	√√	√√√	√√√√

pageres: 除最小核心内容之外还有 API 章节；居中 logo 图是加分项
bluebird: 简洁到没有安装和 demo，过犹不及，给2分；清新的 website 主页和感觉上的极简是加分项
httpie: 大量的 badges、topic、点赞数；最小核心内容隐藏在大量篇幅之中，酌情扣1分。有目录，结构完备给满分；但内容太长扣风格分，不简洁
joe: API 加分；GIF 恰如其分地展示了工具的用法给满分；没有 LICENSE 扣一分结构分
hicat: develop tips 加分；没有 LICENSE 扣分
github-changelog-generator: 重要信息次序正确。参数使用说明加分，build/coverage badge 加分。极为啰嗦扣掉大部分分数
enhancd: install 在较后面扣分；风格太繁华：各种 emoji、各种 gif、各种 htmled markdown、各种资源推荐，看完整个人都狂躁了起来。中间有个 features 章节，看起来是一句话就可以说清的东西，扣风格分，不简洁