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 - 深入参考材料的使用指南