README 的四个问题

陌生人打开仓库，几十秒内决定继续读还是关掉。README 的任务就是在这几十秒里回答四个问题，顺序不能乱。

四个问题

四个问题依次是：这是什么、为什么值得关心、怎么用、怎么装。前两个决定读者要不要留下，后两个决定他能不能跑起来。

问题	位置	写砸的样子
这是什么	标题下一行	从公司愿景开始
为什么关心	一句话加演示	堆一排形容词
怎么用	紧跟演示的命令	只丢一个 API 文档链接
怎么装	靠后	把安装步骤放在最前面

用法放在安装之前，因为读者要先看到结果，才愿意执行安装步骤。这个顺序违反了很多项目的习惯，但它符合读者做决定的顺序。

顶部一行话要具体到能判断适用场景，「一个快速的构建工具」不如「把 TypeScript 单文件打包成可执行的二进制」。

最小骨架

# toolname

把 CSV 转成 JSON，保留列顺序。

```bash
toolname convert input.csv > out.json
```

## 安装

```bash
brew install toolname
```

示例里用真实文件名和真实输出，占位符要能直接替换。安装只保留一条主路径，其他平台折叠到后面的小节，别让首屏变成包管理器大全。

常见错误

• 首屏是徽章墙，正文要滚动才出现
• 安装写在用法前面
• 示例引用了仓库里不存在的文件
• 缩写没有展开，读者不知道项目名什么意思
• 链接指向 main 分支的具体行号
• 没有说明支持哪些版本
• 没有列出依赖和最低版本
• 故障排查散落在 issue 里，没有汇总
• 贡献入口藏在文件末尾
• 没有许可证
• 把完整 changelog 贴进 README
• 代码块不标语言，高亮和复制都会变差
• 用了多个一级标题，目录结构散掉

链接要用 tag 或 commit hash 固定，行号会随代码漂移。指向外部文档时也一样，能锚定版本就不要锚定最新版。

文档也要维护

README 里的示例会腐烂：函数改名、参数改顺序、默认值变化，示例却没人跑。发版前至少手动执行一遍，把输出和文档对齐。

能自动执行更好：Rust 的 cargo test --doc、Python 的 doctest、mdbook test 都会运行文档里的代码。README 里的 shell 片段缺少这种机制，可以放进 CI 的 smoke test 脚本；改接口时一起改示例，比事后补文档便宜得多。

三类读者

同一个 README 要服务三类人：评估项目的用户、准备贡献的开发者、接手维护的同事。三者的入口不同，混在一起会让首屏变得臃肿。

读者	关心什么	入口
用户	用法、限制和替代方案	README 顶部
贡献者	开发环境、测试命令、代码结构	CONTRIBUTING.md
维护者	发布流程、架构决策、已知债务	docs/ 或 ADR

主 README 保持短，把开发细节放进 CONTRIBUTING.md，把设计决策放进 docs/ 或 ADR 目录，再用相对链接连起来。读者按需跳转，不必在首屏翻过一整页构建说明。

相对链接在 GitHub 和本地编辑器里都能用，比绝对 URL 更稳；指向仓库内文件时不要带 main 分支前缀，否则 fork 之后链接会指向原仓库。README 的长度不是问题，顺序才是：三类读者都需要的信息留在顶部，只有贡献者关心的内容折叠或外链。

示例的选择

示例要覆盖大多数人的主路径，而不是展示作者最得意的用法。一个能跑通的最小例子，比五个带十行配置的高级例子更有用。

• 用真实场景的数据，不用 foo、bar
• 展示输出，让读者知道成功是什么样
• 错误处理放在单独的「故障排查」小节
• 示例里的路径和端口不要依赖作者本机
• 每个示例只演示一个概念

示例越长，读者越可能跳过。把完整脚本放进 examples/ 目录，README 里只留三五行，需要的人自己点进去看。