我们在Github上创建项目的时候，常常会看到默认使用README文件初始化该项目，然后在新建项目的根目录下就会生成README.md文件。
有好的README文档的项目不一定是一个好的开源项目，但一个好开源项目一定有一个好的README
1. README文档的组成部分
- （一）国际化
- （二）项目工程介绍
- （三）项目的使用效果图
- （四）项目特点
- （五）项目的基本结构（架构）
- （六）集成方式
- （七）使用方法
- （八）混淆
- （九）关于作者/组织及交流方式等信息。
- （十）贡献者/贡献组织
- （十一）鸣谢
- （十二）版权信息
一）国际化
github是面向全球的一个开源网站，所以不要局限于中文文档，建议写一个英文的README，让来自全球的人都能更方便的了解你的项目。推荐写法，在REAMDE开头写上国际化引用地址
（二）项目工程介绍
项目介绍是必不可少的，它能让别人快速了解项目。项目介绍主要包括：
- 项目名称、logo（没有logo就不写）
- 这个开源项目是做什么的？
- 这个项目是什么语言编写的？
- 这个项目目前被多少人用到了，有多少好评等？
- 项目维护、依赖更新状态（如果有的话，这也可以用）等
- 项目可用版本及其他版本，以及每个版本的更新信息记录
- Demo 或官网地址（如果有）
上述案例里面那些图标，请参考这个网站 Shields.io，打开之后想用哪个直接复制就可以了，同时它也支持自定义样式。
（三） 项目的使用效果图
如果是一些自定义控件或者项目的演示效果的，基本都会放上演示效果图，可以是图片，也可以是gif图。
建议：静态的页面的放截图，交互很复杂的建议放gif图。 如果功能比较多，建议每个功能一张效果图。
（四）项目特点
主要是介绍项目的特点，方便别人查看和了解该项目。
（五）项目的基本结构（架构）
这里主要介绍项目的各个组成部分，如果是框架，可以附带架构图解；如果是其他的，可以提供一些UML分析图，顺便分析一下源码也行的。
（六）集成方式
一般的项目传到jcenter上面或者AS插件传到jetbrains的话 一般会附带相关的集成方式的说明。（如果没有这些措施的话，这一步可以略过不看。）
（七）使用方法
一般的README必不可少的，最重要的就是用法，主要包括：安装，运行，编译，部署，debug，该github上的这个库如何在自己的项目中使用，以及需要注意的问题，版本更新适配问题等等。
（八）混淆
一般来说，开源库都会设置一些混淆规则的，部分项目由于项目类型特殊之处，所以就没有混淆这一项，具体的看开源项目来定。
（九）关于作者/组织及交流方式等信息。
这个就很灵活了，不是每一个必备，当然写出来方便大家联系作者，也是很好的。可以写一下作者或者组织的联系方式，微信，邮箱，博客，微博，甚至支付宝转账二维码等都是可以放上去的。
（十）贡献者/贡献组织
比如 谷歌推出的 sample 里面就有贡献者/贡献组织信息
（十一）鸣谢
这个主要是引用了哪些开源技术，这里可以做一些鸣谢，表示对别人的尊重，其实也是一个引用声明，避免因为版权而引起不必要的纠纷。
（十二）版权信息
版本很重要，开源许可证很重要，如果没有生命版权，可能会因为一些侵权行为而无法很好的维权，版权信息可以保护作者的权益（个人理解）。
世界上的开源许可证，大概有上百种。很少有人搞得清楚它们的区别。最流行的有六种：GPL、BSD、MIT、Mozilla、Apache、LGPL
乌克兰程序员Paul Bagwell，画了一张分析图，说明应该怎么选择。这是我见过的最简单的讲解，只用两分钟，你就能搞清楚这 六种许可证之间的最大区别。
2. 优秀的README文档应该包含哪些内容？
-
项目描述
-
如何运行
-
业务介绍
-
项目备注
每一项都有哪些作用？
-
项目描述
需要说明我们的项目名，项目功能简述，代码仓库地址，以及该项目的第一负责人。谁交接给我们的项目，谁就是该项目的第一负责人。
-
如何运行
开发环境配置。一般是我们需要的一些运行环境配置。
开发&发布 命令。我们怎么通过命令开启本地开发，以及构建发布。
代理配置。如果我们的项目在本地开发时需要用到一些代理工具，例如fiddler或whistle等，我们需要列出代理的配置项。最好是直接导出一个代理配置的文件，放在项目下
发布。如果我们有用到一些发布平台，最好贴上项目的发布模块和发布单，减少我们发布的时间成本。
错误告警及监控。相信我们平常都会对线上的项目部署错误告警和监控日志的服务，方便我们及时排查现网问题，这里我们可以加入项目的一些监控属性ID
接口API。这里我们需要贴入项目中拉去的后台接口地址以及描述，还有我们的接口负责人，当后台服务异常，可以直接联系到后台同学。
数据上报。我们在平常项目里都有加入一些数据上报，给产品同学统计业务数据用，这里我们最好阐述下都有哪些数据的上报。如果上报出问题，产品妹子找过来，我们不至于是一脸懵逼。
-
业务介绍
对于前端来说，我们一个项目可能不止一个页面，那么我们需要给出以下信息:
业务入口地址及渠道链接 即我们整个项目的入口页面，或者比较重要的页面地址。一般入口页面，我们可能会在多个渠道进行投放，那么需要列出所有的渠道链接
-
各页面及描述 列出我们项目内的所有页面信息，比如下面这样：
页面目录 页面描述 页面链接 参数描述 index 首页 https://xxx.com 无 -
项目备注 项目中需要告诉其他开发者一些关键信息，比如我们页面打包构建，需要注意哪些问题等等，这些信息虽然不是必须的，但是可以帮助其他开发者降低开发的风险成本。
3. 一个有逼格的README应有的样子
项目名称
这里再写一句骚气又精准的话描述你的项目吧。
上手指南
写几句这样的话概括接下来的内容：以下指南将帮助你在本地机器上安装和运行该项目，进行开发和测试。关于如何将该项目部署到在线环境，请参考部署小节。
安装要求
列出运行该项目必须要具备的条件以及必须要安装的软件，最好给出具体的安装步骤。
- 必须安装我
- 我也必须安装
- 安装我也是必须的
安装步骤
一步一步地说明怎么去搭建环境，怎么让项目跑起来。
首先你需要
- 干这件事
- 干那件事
- 继续干这件事
…一直到完成。
最后阐述安装完成后的情况，展示下Demo
测试
解释说明一下如何运行该系统的自动测试部分。
分解为端对端测试
解释这些测试是什么以及为什么要做这些测试
1.我是个栗子
2.我也是个栗子
3.我是栗子的哥哥
代码风格测试
解释这些测试是什么以及为什么要做这些测试
1.我是个栗子
2.我也是个栗子
3.我是栗子的哥哥
部署
对以上的安装步骤进行补充说明，描述如何在在线环境中安装该项目。
使用到的框架
Dropwizard - Web框架
Maven - 依赖属性管理
ROME - 生成RSS源
贡献者
请阅读***CONTRIBUTING.md*** 查阅为该项目做出贡献的开发者。
版本控制
该项目使用SemVer进行版本管理。您可以在repository参看当前可用版本。
作者
地球上的盐味
您也可以在贡献者名单中参看所有参与该项目的开发者。
版权说明
该项目签署了MIT 授权许可，详情请参阅 LICENSE.md
鸣谢
该项目参考了XXX的 XXX
灵感来源于XXX
感谢女友的支持和陪伴
以上。其实在实际的写作当中，也并不一定要完全跟着这个框架来，可以根据项目情况进行增删。比如稍微复杂点的项目，就要更多的纬度去说明，那么在开头就需要列出目录（Table Of Content）。另外，图片展示也是一种常用的手段，多放图片，会让你的文档更有趣味。
如何写一个优秀的GitHub项目README文档？(其他比较好的参考文章)
https://www.cnblogs.com/shiyanlou/p/10312859.html
https://www.cnblogs.com/wj-1314/p/8547763.html