规范书写GitHub中的README

概述

编写并规范README自述文件的好处

• 节约你我他的时间，让人一目了然项目的用途、用法等
• 有利于项目的传播，吸引志同道合的朋友，让更多的贡献者（技术或捐助等）参与进来
• 在上述基础上，可以使优秀的项目长期得到维护，不至于荒废
• 添加了开源许可协议等声明，避免了日后可能的纷争

怎样才算是写好了README自述文件

当人们能够不用看你的项目代码就可以使用你的项目的时候，你的基本自述文件算是完成了。

基本要求

1. 大写文件名且必须为Markdown文件，README.md
2. 若支持i18n，则自述文件需要分别命名，需符合BCP 47的非区域子标记（Subtag），例如：README.ZH.md（中文），README.md 默认为英语
3. 其中包含的链接需可访问，代码部分不能直接贴，需以代码块形式显示
4. 自述文件有一定的书写顺序和必须包含的标题项，从上至下大致为：

• 标题（一般与仓库名一致）
• 横幅Logo（可选，相对路径链接到本地存储库图片或相应网站上等）
• 徽标Badge（用换行符分隔）
• 简短的项目描述（最好用一行即可描述清楚）
• 详细说明，最好配流程图等（可选）
• 内容列表/目录，带链接（可选，一般在篇幅较大时采用，目录从下一节开始且至少有一个深度，即含有子标题，目录较短的话可以有三到四个深度）
• ...
• 这里是主体部分，主要描述项目背景、如何配置、安装和使用等，自由发挥
• ...
• 致谢（可选）
• 参与贡献方式（Contributing，一般链接到贡献文件和issues，可列出贡献者）
• 许可证（License，声明许可证标识符或全名， 可链接到本地存储库的 LICENSE 文件并声明持有者）

参考资料

1. 标准化README