从 GitHub 2021 年度报告谈开源技术项目的文档问题

        最近， Github发布了它每年一度的分析报告，https://octoverse.github.com/，内容很丰富，国内各大技术媒体也都有相关的报道，他们各有各的解读，有的是从中美开发者数量来解读，例如中国开发者数量约为700万；有的是从开发语言流行度来解读，比如最流行的开发语言还是JavaScript。我现在想从另外一个角度来解读这份报告，即documentation 文档。

        这份报告里面有一个特定的部分是描述文档相关的统计情况和发展趋势。我们来仔细看一看。

        首先是概述，repo中的Readme，Contribution guidelines and issues 是一个开源项目的秘密，保持它们update to date、detail、reliable，能提升开发人员50%的生产力。

        我们先来看Readme文档部分，Report的overview中提到readme文档的重要性。

  

 

 

 

 

 

从统计图能看出，85%以上的开源项目都有了Readme文档。

然后我们来看Contribution Guidelines，显然越来越多的开源项目中有这份文档。

之后，Report也提到了Issue， issue也是很重要的文档，其中被标签为“Good First Issue”的issue是项目特意标出、

适合给new comer来完成第一个contribution的issue，Report表明repo如果“Good First Issue”的比例超过40%，能多获得21%的新贡献者。

最后，报告里说“Documentation is good for productivity and culture - it's a win-win”。

 

ok，对于报告的解读已经告一段落，那么对于一个开源项目来说，究竟哪些文档是必不可少的，而且这些文档最低限度需要达到什么质量要求呢？

带着这个问题，我组织了一个workingroup，邀请了KubeSphere社区的周鹏飞同学，和StreamNative社区的Yu和Jennifer同学，经过讨论和协作，大家一起完成一份文档即《开源技术项目的文档指南》，链接在这里---https://github.com/CommunityLeadershipDevelopment/doc_guide.

我们认为，一个希望进行社区协作的开源技术项目，至少需要如下4份文档：

1. Readme： 用于描述项目的最基本信息，并用于链接到其他重要信息
2. Quick Start：用于让用户在10分钟内体验到该技术项目的一个场景，从而让用户持续深入进去
3. Contributing Guide：描述给这个项目做贡献相关的步骤和方法
4. Code of Conduct：用于规定社区协作的最基本礼仪

其中每个文档指南都有自己最基本的质量要求，比如Readme文档需要包含项目介绍，和到QuickStart，Contributing Guide，Code of Conduct，License的链接，项目介绍需要通俗易懂；Quick Start文档需要包含如下模块和具体步骤：使用软件的先决条件，如何下载，如何安装，如何使用，文档需要易使用，易查找，易理解等。

这个文档指南的使用场景如下：

1. 开源项目的负责人可以参考此文档，检查自己的开源技术项目是否已有这些文档，这些文档是否达到本指南的各个质量要求
2. 开源项目的文档负责人可以参考此文档，把这些文档作为自己项目的文档模版，按需增补自己项目的特定内容，从而快速达到文档完备的基本要求
3. 本指南作为开放原子基金会TOC的工作文档一部分，作为导师帮助孵化项目达到文档质量要求的参考和Checklist
4. 作为开源项目技术传播社区（包括布道，文档等）的一个初始产出

目前这份指南已经出了1.0版本，也希望国内开源项目的同学可以一起来参与和讨论。

https://github.com/CommunityLeadershipDevelopment/doc_guide.

而且checklist已经正式作为开放原子开源基金会的导师工作手册的一部分，将帮助基金会内孵化项目的导师来进行项目文档质量的check。

另外，开源项目技术传播社区的二维码如下，欢迎大家扫码加入，和我们一起讨论开源项目技术传播的事情，包括技术文档协作，技术线上和线下布道等等。