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 - 深入参考资料指南