README 怎么写：让陌生人在五分钟内跑起来

七段结构

• 1. 一句话说明：这个项目解决什么问题。
• 2. 安装：完整命令，含前置依赖。
• 3. 快速开始：最少步骤跑通一次。
• 4. 使用示例：覆盖最常见的两个场景。
• 5. 配置：每个配置项一行说明。
• 6. 已知限制：不支持的场景如实列出。
• 7. 贡献与许可：指向对应文档。

命令的写法

• 所有命令放在独立代码块中，可整段复制执行。
• 命令里的参数用真实值（不要 <占位符> 混在可复制文本里）。
• 标注命令的运行目录与前置条件。

三个常见失败

• 只有 API 文档没有快速开始——读者跑不起来就走了。
• 示例依赖未说明的隐藏步骤。
• README 与代码脱节（版本更新后没同步）。

自查

找一台干净的环境（或同事的电脑），只照 README 操作——能不能在五分钟内跑通，就是唯一的标准。