撰写有效READMESkill crafting-effective-readmes

---

name: 撰写有效README description: 在编写或改进README文件时使用。并非所有README都相同——提供与受众和项目类型匹配的模板和指导。

撰写有效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 - 深入参考材料的指南