用途
该技能用于在撰写或改进 README 文件时提供模板与指导,核心出发点是:README 应回答读者的问题,而不同读者需要不同信息。例如,开源项目贡献者所需的背景与“未来的自己”打开配置文件夹时所需的信息并不相同。因此使用时始终要问:谁会读这份 README,他们需要知道什么?
主要流程
第一步:识别任务。需要先确认当前在做哪类 README 工作,包括:创建(新项目、尚无 README)、添加(需要记录新内容)、更新(能力已变化、内容过时)、审查(检查 README 是否仍然准确)。
第二步:提出任务相关问题。
- 创建初始 README 时:项目是什么类型?用一句话说明它解决什么问题?达成“它能跑起来”的最快路径是什么?有没有值得强调的内容?
- 添加章节时:需要记录什么?应放在现有结构的哪个位置?谁最需要这些信息?
- 更新现有内容时:发生了什么变化?阅读当前 README,找出过时章节;提出具体修改建议。
- 审查/刷新时:阅读当前 README;对照项目实际状态(如 package.json、主文件等)检查;标出过时章节;如果存在“最后审查”日期则更新它。
第三步:始终追问。草稿完成后询问:“还有什么值得强调或包含、而我可能遗漏的内容?”
项目类型与关键章节
技能按项目类型区分读者与关键章节,并提供对应模板:
- 开源(Open Source):读者为全球贡献者与用户;关键章节为安装、用法、贡献、许可证;模板 templates/oss.md。
- 个人(Personal):读者为未来的自己、作品集浏览者;关键章节为它做什么、技术栈、心得;模板 templates/personal.md。
- 内部(Internal):读者为团队成员、新入职者;关键章节为安装配置、架构、运行手册;模板 templates/internal.md。
- 配置(Config):读者为未来感到困惑的自己;关键章节为这里有什么、为什么、如何扩展、注意事项;模板 templates/xdg-config.md。
若不清楚项目类型应询问用户,不要对所有项目默认采用开源模板。
基本章节(所有类型)
每份 README 至少需要:名称(自解释的标题)、描述(一到两句话说明是什么和为什么)、用法(如何使用,示例会更有帮助)。
参考资料
- section-checklist.md:按项目类型说明应包含哪些章节。
- style-guide.md:常见 README 错误与行文指导。
- using-references.md:关于更深入参考材料的指南。
限制
所提供的资料未说明该技能的运行环境、安装方式、收费模式或适用平台的限制,这些信息暂未提供。