版權(quán)聲明：本文為博主原創(chuàng)文章，未經(jīng)博主允許不得轉(zhuǎn)載。http://www.itdecent.cn/p/813b70d5b0de
轉(zhuǎn)載請標(biāo)明出處：
http://www.itdecent.cn/p/813b70d5b0de
本文出自 AWeiLoveAndroid的博客
看過很多開源庫，發(fā)現(xiàn)有些庫的文檔寫的一團(tuán)糟，有的甚至就是一個(gè)標(biāo)題，讓你自己下載之后運(yùn)行，自己摸索，看的很頭疼。而那些使用量大的庫的文檔寫的很標(biāo)準(zhǔn)，很詳細(xì)，看的很舒服。
README文檔寫的好的話能減少很多使用成本，能幫助這個(gè)庫讓更多人了解，更多的人用，可以說好的文檔就是一個(gè)門面。
有好的 README 文檔的項(xiàng)目不一定是一個(gè)好開源項(xiàng)目，但一個(gè)好開源項(xiàng)目一定有一個(gè)好的 README。
下面就簡單的總結(jié)一下README文檔規(guī)范寫法。（這只是我個(gè)人根據(jù)github上幾百個(gè)大型開源庫總結(jié)出來的，如你有更好的意見，歡迎留言。）
一、README文檔的組成部分
看過很多開源框架的README文檔，綜合一下，大概有以下幾部分組成：
- （一）國際化
- （二）項(xiàng)目工程介紹
- （三）項(xiàng)目的使用效果圖
- （四）項(xiàng)目特點(diǎn)
- （五）項(xiàng)目的基本結(jié)構(gòu)（架構(gòu)）
- （六）集成方式
- （七）使用方法
- （八）混淆
- （九）關(guān)于作者/組織及交流方式等信息。
- （十）貢獻(xiàn)者/貢獻(xiàn)組織
- （十一）鳴謝
- （十二）版權(quán)信息
二、下面就每個(gè)部分簡單的分析一下：
（一）國際化
github是面向全球的一個(gè)開源網(wǎng)站，所以不要局限于中文文檔，建議寫一個(gè)英文的README，讓來自全球的人都能更方便的了解你的項(xiàng)目。推薦寫法，在REAMDE開頭寫上國際化引用地址：
比如：
（二）項(xiàng)目工程介紹
項(xiàng)目介紹是必不可少的，它能讓別人快速了解項(xiàng)目。項(xiàng)目介紹主要包括：
- 項(xiàng)目名稱、logo（沒有l(wèi)ogo就不寫）
- 這個(gè)開源項(xiàng)目是做什么的？
- 這個(gè)項(xiàng)目是什么語言編寫的？
- 這個(gè)項(xiàng)目目前被多少人用到了，有多少好評等？
- 項(xiàng)目維護(hù)、依賴更新狀態(tài)（如果有的話，這也可以用）等
- 項(xiàng)目可用版本及其他版本，以及每個(gè)版本的更新信息記錄
- Demo 或官網(wǎng)地址（如果有）
效果圖如下所示：
英文版：
中文版：
- 上述案例里面那些圖標(biāo)，請參考這個(gè)網(wǎng)站 Shields.io，打開之后想用哪個(gè)直接復(fù)制就可以了，同時(shí)它也支持自定義樣式。
（三） 項(xiàng)目的使用效果圖
如果是一些自定義控件或者項(xiàng)目的演示效果的，基本都會(huì)放上演示效果圖，可以是圖片，也可以是gif圖。
建議：靜態(tài)的頁面的放截圖，交互很復(fù)雜的建議放gif圖。 如果功能比較多，建議每個(gè)功能一張效果圖。
示例如下：
LoveHeartView使用示意圖如下圖所示：
（四）項(xiàng)目特點(diǎn)
主要是介紹項(xiàng)目的特點(diǎn)，方便別人查看和了解該項(xiàng)目。
比如 360的RePlugin框架的特點(diǎn)就寫的很詳細(xì)：
（五）項(xiàng)目的基本結(jié)構(gòu)（架構(gòu)）
這里主要介紹項(xiàng)目的各個(gè)組成部分，如果是框架，可以附帶架構(gòu)圖解；如果是其他的，可以提供一些UML分析圖，順便分析一下源碼也行的。
比如 360的RePlugin架構(gòu)圖解 如下所示：
（六）集成方式
一般的項(xiàng)目傳到j(luò)center上面或者AS插件傳到j(luò)etbrains的話 一般會(huì)附帶相關(guān)的集成方式的說明。（如果沒有這些措施的話，這一步可以略過不看。）
比如 okhttp 就有詳細(xì)的3種集成方式：
一個(gè)是下載Jar包；一個(gè)是引用Maven庫；第三個(gè)是添加Gradle依賴：
（七）使用方法
一般的README必不可少的，最重要的就是用法，主要包括：安裝，運(yùn)行，編譯，部署，debug，該github上的這個(gè)庫如何在自己的項(xiàng)目中使用，以及需要注意的問題，版本更新適配問題等等。
這里就拿 Glide 舉例說明，Glide里面有一個(gè)詳細(xì)的wiki使用文檔的，首頁的README里面也寫了一個(gè)簡單的基本用法，如下圖所示：
（八）混淆
一般來說，開源庫都會(huì)設(shè)置一些混淆規(guī)則的，部分項(xiàng)目由于項(xiàng)目類型特殊之處，所以就沒有混淆這一項(xiàng)，具體的看開源項(xiàng)目來定。
例如LitePal這個(gè)開源庫的混淆 如下圖所示：
（九）關(guān)于作者/組織及交流方式等信息。
這個(gè)就很靈活了，不是每一個(gè)必備，當(dāng)然寫出來方便大家聯(lián)系作者，也是很好的?？梢詫懸幌伦髡呋蛘呓M織的聯(lián)系方式，微信，郵箱，博客，微博，甚至支付寶轉(zhuǎn)賬二維碼等都是可以放上去的。
例如 blankj的AndroidUtilCode這個(gè)庫為例，為了避免打廣告嫌疑，我做了打碼處理：
（十）貢獻(xiàn)者/貢獻(xiàn)組織
比如 谷歌推出的 sample 里面就有貢獻(xiàn)者/貢獻(xiàn)組織信息，如下圖所示：
（十一）鳴謝
這個(gè)主要是引用了哪些開源技術(shù)，這里可以做一些鳴謝，表示對別人的尊重，其實(shí)也是一個(gè)引用聲明，避免因?yàn)榘鏅?quán)而引起不必要的糾紛。
例如：我寫的這個(gè)庫 https://github.com/AweiLoveAndroid/CommonDevKnowledge/blob/master/interview/summary.md 里面就寫了鳴謝。
（十二）版權(quán)信息
版本很重要，開源許可證很重要，如果沒有生命版權(quán)，可能會(huì)因?yàn)橐恍┣謾?quán)行為而無法很好的維權(quán)，版權(quán)信息可以保護(hù)作者的權(quán)益（個(gè)人理解）。
世界上的開源許可證，大概有上百種。很少有人搞得清楚它們的區(qū)別。最流行的有六種：GPL、BSD、MIT、Mozilla、Apache、LGPL
烏克蘭程序員Paul Bagwell，畫了一張分析圖，說明應(yīng)該怎么選擇。這是我見過的最簡單的講解，只用兩分鐘，你就能搞清楚這 六種許可證之間的最大區(qū)別。
比如 Picasso 里面的版權(quán)信息，如下圖所示：
