crafting-effective-readmes

# 撰写有效的 README ## 概述 README 回答了受众可能会有的问题。不同的受众需要不同的信息——开源项目的贡献者需要的背景信息与未来打开配置文件夹的你自己是不同的。 **始终询问：** 谁会读这个，他们需要知道什么？ ## 流程 ### 第 1 步：识别任务 **询问：** “你正在处理什么 README 任务？” | 任务 | 何时 | |------|------| | **创建** | 新项目，尚无 README | | **添加** | 需要记录新内容 | | **更新** | 功能已更改，内容过时 | | **审查** | 检查 README 是否仍然准确 | ### 第 2 步：任务特定问题 **创建初始 README：** 1. 项目类型是什么？（见下文项目类型） 2. 用一句话说明它解决了什么问题？ 3. 实现“它能运行”的最快路径是什么？ 4. 有什么值得强调的吗？ **添加章节：** 1. 需要记录什么？ 2. 在现有结构中应该放在哪里？ 3. 谁最需要这些信息？ **更新现有内容：** 1. 发生了什么变化？ 2. 阅读当前 README，识别过时的章节 3. 提出具体的修改建议 **审查/刷新：** 1. 阅读当前 README 2. 对照实际项目状态（package.json、主要文件等）进行检查 3. 标记过时的章节 4. 更新“最后审查”日期（如果存在） ### 第 3 步：始终询问 草拟完成后，询问：**“还有什么我可能遗漏的需要强调或包含的内容吗？”** ## 项目类型 | 类型 | 受众 | 关键章节 | 模板 | |------|----------|--------------|----------| | **开源** | 全球贡献者、用户 | 安装、使用、贡献、许可 | `templates/oss.md` | | **个人** | 未来的自己、作品集浏览者 | 功能、技术栈、心得 | `templates/personal.md` | | **内部** | 队友、新员工 | 设置、架构、运行手册 | `templates/internal.md` | | **配置** | 未来的自己（困惑时） | 内容、原因、扩展方法、注意事项 | `templates/xdg-config.md` | 如果不清楚，请**询问用户**。不要默认所有项目都使用开源模板。 ## 必备章节（所有类型） 每个 README 至少需要： 1. **名称** - 一目了然的标题 2. **描述** - 用 1-2 句话说明是什么 + 为什么 3. **使用方法** - 如何使用（示例很有帮助） ## 参考资料 - `section-checklist.md` - 按项目类型应包含的章节 - `style-guide.md` - 常见的 README 错误和写作指导 - `using-references.md` - 深入参考资料的指南