README? LandingPage

最近看了不少开源项目的 README，有些看起来很轻松、很容易达成看readme的预期，有些看起来很费劲，还有些爱惜笔墨，寥寥数语简单介绍。

看起来轻松的那些，大多结构简单明了，有着明显的引导性。看起来费劲的那些，无一例外，包含详细的安装步骤、配置项、API 参数，还有一长串恨不得把项目解释到底的文字。写的很认真，读起来很痛苦，像是在读开发日志。项目名下面那一段没看懂，往下翻又是一屏 badge，最后关掉页面。文档或许很完整，但实在看不下去。

因而我开始想，README 的作用是什么？怎样才算是一个好的 README？

仓库的门面

打开一个陌生仓库时，我通常不会从头逐字读到尾。先看项目名和那句简介，再找截图或代码示例，接着判断它和我有没有关系。如果仍然有兴趣，才会继续找安装方法、文档和示例。

这个过程跟访问产品网站很像。

README 开头真正要回答的，应该是几个很朴素的问题：这是什么，我为什么要在意，它大概长什么样，我能不能很快试一下。

所以，一句清楚的定位往往比一排徽章更有用。截图、GIF、终端录屏是在帮读者减少猜测。一个 CLI 工具跑起来是什么样，一个组件库最终能做出什么，一个桌面应用的交互是否顺手，很多时候看十秒演示就够了，没必要先读五百字。

代码库也需要一点 “show, don’t tell”。而且越是技术项目，越容易忘记这件事。

换个角度看，README 更像网站的 landing page。它当然要提供信息，不过它还有一个更现实的任务：接住一个刚刚点进仓库、耐心不多、对项目也没什么了解的人，然后告诉他接下来往哪里走。

渐进式引导

landing page 不会试图当场解释完整个产品，它会安排一条路径。README 也一样。

最舒服的阅读体验，大概是这样的：先知道项目解决什么问题，再看到一个示例，然后用最短的步骤跑起来。等第一次成功出现，读者才可能会去找更详细的配置、架构说明或贡献指南。

这里的 “最短” 很重要。Quick Start 不是安装手册的缩写版，而是一次快速体验。复制几行命令，得到一个明确结果。中间如果需要申请密钥、修改五个配置文件、理解一套目录结构，那就不太 quick 了。至少应该把这些前置条件说清楚，别让人执行到一半才发现少了东西。

我挺喜欢 Mole 的 README。视觉记忆鲜明，先展示结果，项目定位之后，马上放出终端界面和清理空间的数据，读者几乎不用解释就能明白它做什么、效果如何。安装只需要一行 Homebrew 命令，常用操作也配有真实输出，特别适合 CLI 工具。

你不需要先理解它的全部设计，先看到页面跑起来再说。

这种引导感来自顺序。读者还不知道项目是什么时，不要先讲贡献流程；还没跑起来时，不要急着展开内部架构；刚产生兴趣时，也别给他扔一份文档站外链。

内容有取舍

README 经常越写越长，原因也很好理解。每次有人问问题，就补一段；每次加功能，再补一节。几年后，它成了安装指南、FAQ、架构文档和版本历史的混合物。什么都有，入口反而不见了。

我现在更愿意把 README 看成文档系统的首页。它负责给出项目全貌和最短路径，详细内容交给专门的文档。安装遇到分支场景，可以进入 Getting Started；复杂配置去 Configuration；设计取舍和模块关系放进 Architecture；贡献者需要的开发环境、测试和发布流程，也值得有单独的 Contributor Guide。

这样做一方面保持了整洁，另一方面应对了带着不同目的来的不同访问者。第一次访问的人想知道值不值得试，已经在使用的人要查参数，准备贡献的人关心本地开发。把他们都留在同一个超长页面里显然不合适。

Scalar 的 README 很像一个完整的产品引导页。它先用一句话说明定位，紧接着展示 API Reference 和 API Client 的实际界面，再提供可以直接运行的最小示例。读者不用先研究项目结构，就能看到效果、理解用途，并马上试一次。更详细的配置、组件和子项目则被放在后面，信息很多，但阅读路径没有乱。

符合项目调性

不同类型的产品，通常有有风格迥异的 landing page，我认为 README 也理应如此。

如果是命令行工具，最有说服力的内容通常是一段真实的命令和输出。库或 SDK 更适合给一个十来行的可运行示例，让人迅速看懂 API 的样子。桌面应用和 Web 应用应该尽早展示界面，最好还能看到一次完整操作。基础设施项目不容易靠截图说明白，架构图、部署边界和一个最小配置会更合适。至于数据可视化工具，结果本身就是证据，notecharts 把图表示例直接摆出来，读者一眼就能判断它是不是自己想要的东西。

有些项目最该展示的不是功能，而是差异。如果市场上已经有很多类似工具，一段坦率的 “Why” 会比泛泛的 feature list 更有效。它可以说明为什么又做了一个，取舍在哪里，哪些场景适合，哪些场景并不适合。说清边界能省掉双方之后的误会。

带入读者视角

我以前会把 README 当成交付前的整理工作。代码写完，把安装、配置、目录结构补齐，似乎就算完成。现在觉得顺序应该反过来一点：先想清楚一个陌生人如何理解项目，再决定 README 放什么。

这也像是在做产品。第一屏放什么，演示出现在哪里，哪一步算首次成功，读者下一步会点哪个链接，这些都是体验设计。Markdown 很朴素，但朴素不等于没有设计。

一个好的 README 不需要把项目讲完。它让人看懂，让合适的人愿意试一次，也让暂时不合适的人迅速确认这一点。然后，它把已经走到这里的人送到下一份更具体的文档。

做到这里，README 的任务其实已经完成了。