readme-best-practices

README 最佳实践

本指南介绍如何编写 README，让它更像落地页，而不是 API 参考文档。读者会在 3-5 秒内决定是否继续阅读，因此首屏必须足以吸引他们看下去。

README 编写流程

1. 起草一句话介绍 — 用一句醒目、具体的话说明项目的用途，以及人们为何应该关注它。避免使用“一个……工具”这样的表述；力求一语中的。
2. 先写可运行的代码示例 — 在内容的前 5-10 行中放入可直接复制粘贴的示例，位置要早于安装说明。立即展示项目的价值。
3. 添加徽章 — 如果项目已设置 CI／发布流程，就在标题下方直接添加构建状态、版本、许可证和覆盖率徽章。
4. 编写快速入门 — 让读者在 30 秒内从零开始运行，不要使用需要读者自行替换的占位值。
5. 补充支持性章节 — 根据下方结构撰写功能、用法、配置、贡献和许可证等内容，只保留确实有信息量的章节。
6. 检查所有资源和链接 — 发布前确认引用的图片（截图、demo.gif）确实存在于磁盘上，并且内部链接都能正常跳转。
7. 以初次阅读者的视角通读 — 假设自己是第一次看到这个项目，重新阅读首屏；删掉任何无助于读者决定继续阅读还是停止的内容。

开篇亮点

• 以一句醒目介绍开篇，说明项目的用途，以及人们为何应该关注它；不要写“一个……工具”，而要一语中的。
• 在前 5 行中放入可运行的代码示例。在解释安装方法之前，立即展示项目的价值。
• 切勿以“在当今快节奏的世界中……”或类似的空话开篇。
• 切勿以“编程愉快！”或类似的套话收尾。
• 避免使用 AI 营销词语：“无缝”“健壮”“全面”“尖端”“强大”“轻松”。直接说明项目的功能，而不是夸大它的表现。

标准结构

典型的 README 可以按大致如下顺序设置章节；只保留对项目确实有信息量的章节：

1. 标题 + 一句话介绍 — 项目名称和醒目的介绍句。
2. 徽章 — 构建状态、最新版本、许可证、测试覆盖率。
3. 快速演示 — 展示项目运行效果的代码片段、GIF 或截图。
4. 功能 — 使用双列表格，而不是一长串项目符号（见下文）。
5. 安装 — 按包管理器列出准确的安装命令（如果有多个包管理器）。
6. 快速入门／用法 — 可直接复制粘贴的最简示例，以及几个更高级的示例。
7. 配置 — 选项、环境变量、配置文件格式，并注明默认值。
8. API 参考（或其链接）— 适用于公开接口较复杂的库。
9. 常见问题／故障排除 — 列出大家在 issue 中实际会问的 3-5 个问题。
10. 贡献 — 说明如何设置开发环境、运行测试和提交 PR；如果存在 CONTRIBUTING.md，请添加链接。
11. 许可证 — 许可证名称及许可证文件链接。
12. 作者／致谢 — 致谢维护者和主要依赖项。

功能展示

• 使用功能表格（两列：功能、说明），不要使用 **功能：** 项目符号列表；与重复的粗体前缀项目符号相比，表格更便于快速浏览。

| Feature | Description |
|---|---|
| Zero-config | Works out of the box with sensible defaults |
| Streaming | Handles gigabyte-scale files without loading them into memory |
| Type-safe | Full TypeScript definitions, no `any` in the public API |

快速入门要求

• 必须可直接复制粘贴：30 秒内从零开始运行。
• shell 命令前不要加 $，否则会影响复制粘贴。
• 将安装命令和最简用法示例放在一起，不要分散到相距较远的章节中。

npm install awesome-lib

awesome-lib run --input data.csv --output report.json

import { parse } from "awesome-lib";

const result = parse("data.csv");
console.log(result.summary);

文案与格式

• 调整句子的长度和结构——将一句话的段落、简短段落和表格结合起来。清一色长度相近的项目符号会显得像是在凑内容。
• 使用标题帮助读者直接跳转到所需部分；不要强迫读者从头到尾线性阅读。
• 只要可行，就优先使用可运行的示例，而不是用文字描述行为。
• 保持行级格式一致：每种语言或命令使用一个围栏代码块，并为语法高亮明确指定语言标签（```bash、```json）。

徽章

• 使用徽章展示客观且可通过机器核验的信息：CI 状态、已发布版本、许可证、下载量、覆盖率。
• 徽章行应保持简短——3-6 个徽章。徽章堆得太多，就像项目符号堆得太多一样杂乱。
• 常见来源：用于自定义徽章的 shields.io、CI 提供商自带的徽章 Markdown，以及 npm/PyPI 官方徽章代码片段。

资源与链接

• 添加图片链接前，检查引用的资源（demo.gif、截图）是否确实存在于磁盘上——首屏中的图片损坏会立刻损害可信度。
• 验证内部锚点链接（目录、“见下文的配置”）确实指向有效标题。
• 仓库内的资源优先使用相对路径，这样它们在 Git 托管平台和软件包注册表中都能正确显示。

作者 / 联系方式部分

• 为作者 / 维护者添加视觉卡片或徽章，而不是只写“由 username 制作”之类的纯文本——GitHub 个人资料徽章、小头像加链接，或赞助按钮会显得更用心。
• 对于有多位维护者的项目，应列出维护者及其职责或负责领域，而不是简单罗列姓名。

应避免的常见错误

• 开篇就介绍安装，而不是项目价值——读者还不知道为什么要安装。
• 用散文式文字记录每个配置选项，而不是使用表格。
• 让 README 内容偏离实际 CLI/API——无法运行的过时示例比没有示例更糟。
• 将营销用语（“快如闪电”“企业级”）与技术文档混在一起——选择一种语体，并保持技术风格。
• 如果已有生成的参考文档（TypeDoc、Sphinx、godoc），就不要在 README 中重复完整的 API 文档——改为链接到该文档。