如何编写好的README

发表于 更新于 分类于
本文字数： 2.4k 阅读时长 ≈ 4 分钟

在github上了上传了许多仓库，如何更好的管理、使用这些仓库，其中关键的一点在于README的编写。README的目的是向使用者展示仓库的使用方法、来历以及未来的进展。越来越重视写好一个REAMDE，优秀的工程不一定有一个好的README，但是不好的REAMDE一定不是一个优秀的工程

关于这个问题在网上也有许多讨论：如何写好Github中的readme？。当前主要参考了一个关于如何编写标准README的github仓库：RichardLitt/standard-readme

内容列表

下面首先讲解standard-readme提供了README文件编写规范，并结合网上讨论进行相应的调整，然后使用README生成器yo，最后编写一些适应不同场景的README模板

规范

standard-readme提供了一个编写规范，原文和翻译如下

里面提出了README的章节列表：

  • 标题（Title，必须）
  • 横幅（Banner，可选）
  • 徽章（Badges，可选）
  • 简短说明（Short Description，必须）
  • 详细描述（Long Description，可选）
  • 内容列表（Table of Contents，必须）
  • 安全（Security，可选）
  • 背景（Background，可选）
  • 安装（Install，默认必须，对文档仓库而言可选）
  • 用法（Usage，默认是必须的，对于文档仓库而言是可选的）
  • 附加内容（Extra Sections，可选）
  • 应用编程接口（API，可选）
  • 主要维护人员（Maintainers，可选）
  • 致谢（Thanks，可选）
  • 参与贡献方式（Contributing，必须）
  • 许可证（License，必须）

从上到下按需实现相应章节内容，其中横幅指的是仓库logo，内容列表指的是后续章节标题，而不是工程架构

横幅

网上有很多在线设计logo的网站，不过下载是要收费的。找了一个免费的logo设计网站：logoly，还有自定义logo工具：zjykzj/zlogo

协议

参考Adding a license to a repository

可以在线添加新文件，输入文件名为LICENSE或LICENSE.md，选择一个license模板，预览后提交即可

如果要更换协议，直接删除新建一个即可

自定义

standard-readme提供了相对完整的README章节架构，结合网上讨论和实际使用经验，再增加以下4个章节：

  • 中英文
  • 徽章
  • 版本更新日志
  • 待办事项

并更新章节参与贡献方式（Contributing）

中英文

  • 状态：默认是必须的，对于文档仓库而言是可选的
  • 必要条件：
    • None
  • 建议：
    • 准备中英文两份README，相互之间可跳转
    • README.md为英文内容，README.zh-CN.md为中文内容
    • 放置在徽章之后，简短说明之前

徽章

  • 状态：可选
  • 必要条件：
    • 标题为徽章
  • 建议：

规范中已经提到了一个徽章章节，里面添加的是仓库编写、部署过程中使用的工具、规范等相应的徽章，而本章节在于给出自己仓库的专属徽章

徽章生成参考自定义徽章

版本更新日志

待办事项

  • 状态：可选
  • 必要条件：
    • None
  • 建议：
    • 列出后续待完成的事项
    • 按实现顺序从上到下排列

参与贡献方式

在参与贡献方式章节中应该明确是否允许合并请求，并给出进行版本管理的相应规范，比如

完整内容列表

综上所述，完整的内容列表如下：

  • 标题（Title，必须）
  • 横幅（Banner，可选）
  • 徽章（Badges，可选）
  • 中英文(Chinese and English，默认是必须的，对于文档仓库而言是可选的)
  • 简短说明（Short Description，必须）
  • 详细描述（Long Description，可选）
  • 内容列表（Table of Contents，必须）
  • 安全（Security，可选）
  • 背景（Background，可选）
  • 徽章（Badge，可选）
  • 安装（Install，默认必须，对文档仓库而言可选）
  • 用法（Usage，默认是必须的，对于文档仓库而言是可选的）
  • 附加内容（Extra Sections，可选）
  • 应用编程接口（API，可选）
  • 版本更新日志（CHANGELOG，可选）
  • 待办事项（TODO，可选）
  • 主要维护人员（Maintainers，可选）
  • 致谢（Thanks，可选）
  • 参与贡献方式（Contributing，必须）
  • 许可证（License，必须）

生成器

模板

参考：

README_TEMPLATES/

example-readmes

以仓库zjZSTU/PyNet为例，生成不同适用范围的自定义模板。README模板地址：templates

最小README

建立一个最简单基本的README，仅包含必须的章节内容，参考MINIMAL_README.md

  • 标题（Title，必须）
  • 中英文(Chinese and English，默认是必须的，对于文档仓库而言是可选的)
  • 简短说明（Short Description，必须）
  • 内容列表（Table of Contents，必须）
  • 安装（Install，默认必须，对文档仓库而言可选）
  • 用法（Usage，默认是必须的，对于文档仓库而言是可选的）
  • 参与贡献方式（Contributing，必须）
  • 许可证（License，必须）

标准README

完整的实现所有章节内容，参考STANDARD_README.md