开发工具总结(9)之开源项目的README文档的最全最规范写法

版权声明:本文为博主原创文章,未经博主允许不得转载。https://www.jianshu.com/p/813b70d5b0de

转载请标明出处: https://www.jianshu.com/p/813b70d5b0de 本文出自 AWeiLoveAndroid的博客


看过很多开源库,发现有些库的文档写的一团糟,有的甚至就是一个标题,让你自己下载之后运行,自己摸索,看的很头疼。而那些使用量大的库的文档写的很标准,很详细,看的很舒服。

README文档写的好的话能减少很多使用成本,能帮助这个库让更多人了解,更多的人用,可以说好的文档就是一个门面。 有好的 README 文档的项目不一定是一个好开源项目,但一个好开源项目一定有一个好的 README。

下面就简单的总结一下README文档规范写法。(这只是我个人根据github上几百个大型开源库总结出来的,如你有更好的意见,欢迎留言。)

一、README文档的组成部分

看过很多开源框架的README文档,综合一下,大概有以下几部分组成:

  • (一)国际化
  • (二)项目工程介绍
  • (三)项目的使用效果图
  • (四)项目特点
  • (五)项目的基本结构(架构)
  • (六)集成方式
  • (七)使用方法
  • (八)混淆
  • (九)关于作者/组织及交流方式等信息。
  • (十)贡献者/贡献组织
  • (十一)鸣谢
  • (十二)版权信息

二、下面就每个部分简单的分析一下:

(一)国际化

github是面向全球的一个开源网站,所以不要局限于中文文档,建议写一个英文的README,让来自全球的人都能更方便的了解你的项目。推荐写法,在REAMDE开头写上国际化引用地址:

比如:

国际化

(二)项目工程介绍

项目介绍是必不可少的,它能让别人快速了解项目。项目介绍主要包括:

  • 项目名称、logo(没有logo就不写)
  • 这个开源项目是做什么的?
  • 这个项目是什么语言编写的?
  • 这个项目目前被多少人用到了,有多少好评等?
  • 项目维护、依赖更新状态(如果有的话,这也可以用)等
  • 项目可用版本及其他版本,以及每个版本的更新信息记录
  • Demo 或官网地址(如果有)

效果图如下所示:

英文版:

英文版项目介绍

中文版:

中文版项目介绍


  • 上述案例里面那些图标,请参考这个网站 Shields.io,打开之后想用哪个直接复制就可以了,同时它也支持自定义样式。

(三) 项目的使用效果图

如果是一些自定义控件或者项目的演示效果的,基本都会放上演示效果图,可以是图片,也可以是gif图。 建议:静态的页面的放截图,交互很复杂的建议放gif图。 如果功能比较多,建议每个功能一张效果图。

示例如下:

LoveHeartView使用示意图如下图所示:


(四)项目特点

主要是介绍项目的特点,方便别人查看和了解该项目。

比如 360的RePlugin框架的特点就写的很详细:

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的基本用法


(八)混淆

一般来说,开源库都会设置一些混淆规则的,部分项目由于项目类型特殊之处,所以就没有混淆这一项,具体的看开源项目来定。

例如LitePal这个开源库的混淆 如下图所示:

LitePal混淆规则


(九)关于作者/组织及交流方式等信息。

这个就很灵活了,不是每一个必备,当然写出来方便大家联系作者,也是很好的。可以写一下作者或者组织的联系方式,微信,邮箱,博客,微博,甚至支付宝转账二维码等都是可以放上去的。

例如 blankj的AndroidUtilCode这个库为例,为了避免打广告嫌疑,我做了打码处理:

(十)贡献者/贡献组织

比如 谷歌推出的 sample 里面就有贡献者/贡献组织信息,如下图所示:

谷歌推出的sample的贡献者/贡献组织信息

(十一)鸣谢

这个主要是引用了哪些开源技术,这里可以做一些鸣谢,表示对别人的尊重,其实也是一个引用声明,避免因为版权而引起不必要的纠纷。

例如:我写的这个库 https://github.com/AweiLoveAndroid/CommonDevKnowledge/blob/master/interview/summary.md 里面就写了鸣谢。

https://github.com/AweiLoveAndroid/CommonDevKnowledge里面的鸣谢


(十二)版权信息

版本很重要,开源许可证很重要,如果没有生命版权,可能会因为一些侵权行为而无法很好的维权,版权信息可以保护作者的权益(个人理解)。

世界上的开源许可证,大概有上百种。很少有人搞得清楚它们的区别。最流行的有六种:GPL、BSD、MIT、Mozilla、Apache、LGPL

乌克兰程序员Paul Bagwell,画了一张分析图,说明应该怎么选择。这是我见过的最简单的讲解,只用两分钟,你就能搞清楚这 六种许可证之间的最大区别

六种开源许可证之间的区别

比如 Picasso 里面的版权信息,如下图所示:

Picasso 里面的版权信息

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏知晓程序

玩腻了传纸条、漂流瓶,就用它来跟网友分享「小卡片」吧

今天,知晓程序(微信号 zxcx0101)就为你推荐一款有毒的小程序「一起 Up」,在里面,你不仅可以看到其他用户分享的有趣、有内涵的内容,还能将自己的私货与其...

874
来自专栏玉树芝兰

安装 Python 软件包遇错误,怎么办?

本文通过一个命令行转换 pdf 为词云的例子,给你讲讲 Python 软件包安装遇挫折时,怎么处理才更高效?

1542
来自专栏逸鹏说道

.NET技术+25台服务器怎样支撑世界第54大网站

英文原文:StackOverflow Update: 560M Pageviews A Month, 25 Servers, And It's All Abou...

3887
来自专栏程序人生

再谈 API 的撰写 - 总览

背景 去年我写过一篇文章:撰写合格的 REST API。当时 Juniper 裁掉了我们在德州的一支十多人的团队,那支团队有一半的人手在之前的半年里,主要的工作...

4187
来自专栏CSDN技术头条

.NET技术+25台服务器怎样支撑世界第54大网站

【编者按】StackOverflow是一个IT技术问答网站,用户可以在网站上提交和回答问题。当下的StackOverflow已拥有400万个用户,4000万个回...

2467
来自专栏张善友的专栏

让应用程序与您形影相随-PortableApps.com

作为一名 IT 专业人员,您可能会经常需要从一台计算机移到另一台计算机。当您这样做时,您可能会希望能拥有一组随时可用的标准应用程序、工具和文档。满足这些需求的一...

2095
来自专栏Android机动车

Android模块化开发方案

随着业务的不断发展壮大,移动端所承担的功能也越来越重,特别是代码几易其主之后开始变得杂乱无章,牵一发而动全局的事情时常发生。为了应对团队壮大之后的开发模式,我们...

1522
来自专栏编程一生

架构师之路--谈业务的合理架构

952
来自专栏老码农专栏

原 一场版本升级引发的性能血案 - 王者归

1653
来自专栏Golang语言社区

求取一份极致的简单:全链路跟踪中间件探索之路

公司内部的业务系统有近千个,基本上很少有比较孤立的;尤其外部系统,即便用户在页面上一个很普通的操作,后台也需要少则几个多则几十个服务协同完成。以前我们定位调用链...

1271

扫码关注云+社区

领取腾讯云代金券