最近， 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份文檔：
- Readme： 用於描述項目的最基本信息，並用於鏈接到其他重要信息
- Quick Start：用於讓用戶在10分鐘內體驗到該技術項目的一個場景，從而讓用戶持續深入進去
- Contributing Guide：描述給這個項目做貢獻相關的步驟和方法
- Code of Conduct：用於規定社區協作的最基本禮儀
其中每個文檔指南都有自己最基本的質量要求，比如Readme文檔需要包含項目介紹，和到QuickStart，Contributing Guide，Code of Conduct，License的鏈接，項目介紹需要通俗易懂；Quick Start文檔需要包含如下模塊和具體步驟：使用軟件的先決條件，如何下載，如何安裝，如何使用，文檔需要易使用，易查找，易理解等。
這個文檔指南的使用場景如下：
- 開源項目的負責人可以參考此文檔，檢查自己的開源技術項目是否已有這些文檔，這些文檔是否達到本指南的各個質量要求
- 開源項目的文檔負責人可以參考此文檔，把這些文檔作爲自己項目的文檔模版，按需增補自己項目的特定內容，從而快速達到文檔完備的基本要求
- 本指南作爲開放原子基金會TOC的工作文檔一部分，作爲導師幫助孵化項目達到文檔質量要求的參考和Checklist
- 作爲開源項目技術傳播社區（包括佈道，文檔等）的一個初始產出
目前這份指南已經出了1.0版本，也希望國內開源項目的同學可以一起來參與和討論。
https://github.com/CommunityLeadershipDevelopment/doc_guide.
而且checklist已經正式作爲開放原子開源基金會的導師工作手冊的一部分，將幫助基金會內孵化項目的導師來進行項目文檔質量的check。
另外，開源項目技術傳播社區的二維碼如下，歡迎大家掃碼加入，和我們一起討論開源項目技術傳播的事情，包括技術文檔協作，技術線上和線下佈道等等。
