看过很多开源库, 发现有些库的文档写的一团糟, 有的甚至就是一个标题, 让你自己下载之后运行, 自己摸索, 看的很头疼而那些使用量大的库的文档写的很标准, 很详细, 看的很舒服
README 文档写的好的话能减少很多使用成本, 能帮助这个库让更多人了解, 更多的人用, 可以说好的文档就是一个门面
有好的 README 文档的项目不一定是一个好开源项目, 但一个好开源项目一定有一个好的 README
下面就简单的总结一下 README 文档规范写法(这只是我个人根据 github 上几百个大型开源库总结出来的, 如你有更好的意见, 欢迎留言)
一 README 文档的组成部分
看过很多开源框架的 README 文档, 综合一下, 大概有以下几部分组成:
(一)国际化
(二)项目工程介绍
(三)项目的使用效果图
(四)项目特点
(五)项目的基本结构(架构)
(六)集成方式
(七)使用方法
(八)混淆
(九)关于作者 / 组织及交流方式等信息
(十)贡献者 / 贡献组织
(十一)鸣谢
(十二)版权信息
二下面就每个部分简单的分析一下:
(一)国际化
github 是面向全球的一个开源网站, 所以不要局限于中文文档, 建议写一个英文的 README, 让来自全球的人都能更方便的了解你的项目推荐写法, 在 REAMDE 开头写上国际化引用地址:
比如:
国际化
(二)项目工程介绍
项目介绍是必不可少的, 它能让别人快速了解项目项目介绍主要包括:
项目名称 logo(没有 logo 就不写)
这个开源项目是做什么的?
这个项目是什么语言编写的?
这个项目目前被多少人用到了, 有多少好评等?
项目维护依赖更新状态 (如果有的话, 这也可以用) 等
项目可用版本及其他版本, 以及每个版本的更新信息记录
Demo 或官网地址(如果有)
效果图如下所示:
英文版:
英文版项目介绍
中文版:
中文版项目介绍
上述案例里面那些图标, 请参考这个网站 Shields.io, 打开之后想用哪个直接复制就可以了, 同时它也支持自定义样式
(三) 项目的使用效果图
如果是一些自定义控件或者项目的演示效果的, 基本都会放上演示效果图, 可以是图片, 也可以是 gif 图
建议: 静态的页面的放截图, 交互很复杂的建议放 gif 图 如果功能比较多, 建议每个功能一张效果图
示例如下:
LoveHeartView 使用示意图如下图所示:
(四)项目特点
主要是介绍项目的特点, 方便别人查看和了解该项目
比如 360 的 RePlugin 框架的特点就写的很详细:
(五)项目的基本结构(架构)
这里主要介绍项目的各个组成部分, 如果是框架, 可以附带架构图解; 如果是其他的, 可以提供一些 UML 分析图, 顺便分析一下源码也行的
比如 360 的 RePlugin 架构图解 如下所示:
360 的 RePlugin 架构图解
关于 RePlugin 架构的相关说明
(六)集成方式
一般的项目传到 jcenter 上面或者 AS 插件传到 jetbrains 的话 一般会附带相关的集成方式的说明(如果没有这些措施的话, 这一步可以略过不看)
比如 okhttp 就有详细的 3 种集成方式:
一个是下载 Jar 包; 一个是引用 Maven 库; 第三个是添加 Gradle 依赖:
okhttp 的集成方式
(七)使用方法
一般的 README 必不可少的, 最重要的就是用法, 主要包括: 安装, 运行, 编译, 部署, debug, 该 github 上的这个库如何在自己的项目中使用, 以及需要注意的问题, 版本更新适配问题等等
这里就拿 Glide 举例说明, Glide 里面有一个详细的 wiki 使用文档的, 首页的 README 里面也写了一个简单的基本用法, 如下图所示:
Glide 的基本用法
Glide 的基本用法 2
Glide 的基本用法 3
Glide 的基本用法 4
(八)混淆
一般来说, 开源库都会设置一些混淆规则的, 部分项目由于项目类型特殊之处, 所以就没有混淆这一项, 具体的看开源项目来定
例如 LitePal 这个开源库的混淆 如下图所示:
LitePal 混淆规则
(九)关于作者 / 组织及交流方式等信息
这个就很灵活了, 不是每一个必备, 当然写出来方便大家联系作者, 也是很好的可以写一下作者或者组织的联系方式, 微信, 邮箱, 博客, 微博, 甚至支付宝转账二维码等都是可以放上去的
例如 blankj 的 AndroidUtilCode 这个库为例, 为了避免打广告嫌疑, 我做了打码处理:
(十)贡献者 / 贡献组织
比如 谷歌推出的 sample 里面就有贡献者 / 贡献组织信息, 如下图所示:
谷歌推出的 sample 的贡献者 / 贡献组织信息
(十一)鸣谢
这个主要是引用了哪些开源技术, 这里可以做一些鸣谢, 表示对别人的尊重, 其实也是一个引用声明, 避免因为版权而引起不必要的纠纷
例如: 我写的这个库 https://github.com/AweiLoveAndroid/CommonDevKnowledge 里面就写了鸣谢
https://github.com/AweiLoveAndroid/CommonDevKnowledge 里面的鸣谢
(十二)版权信息
版本很重要, 开源许可证很重要, 如果没有生命版权, 可能会因为一些侵权行为而无法很好的维权, 版权信息可以保护作者的权益(个人理解)
世界上的开源许可证, 大概有上百种很少有人搞得清楚它们的区别最流行的有六种: GPLBSDMITMozillaApacheLGPL
乌克兰程序员 Paul Bagwell, 画了一张分析图, 说明应该怎么选择这是我见过的最简单的讲解, 只用两分钟, 你就能搞清楚这六种许可证之间的最大区别[1]
六种开源许可证之间的区别
比如 Picasso 里面的版权信息, 如下图所示:
Picasso 里面的版权信息
本文部分引用以下内容:
http://www.ruanyifeng.com/blog/2011/05/how_to_choose_free_software_licenses.html
来源: http://www.jianshu.com/p/813b70d5b0de