版權聲明：本文為博主原創(chuàng)文章赂蠢，未經(jīng)博主允許不得轉載。http://www.reibang.com/p/813b70d5b0de
轉載請標明出處：
http://www.reibang.com/p/813b70d5b0de
本文出自 AWeiLoveAndroid的博客
看過很多開源庫，發(fā)現(xiàn)有些庫的文檔寫的一團糟人断，有的甚至就是一個標題，讓你自己下載之后運行，自己摸索胶台，看的很頭疼歼疮。而那些使用量大的庫的文檔寫的很標準，很詳細诈唬，看的很舒服韩脏。
README文檔寫的好的話能減少很多使用成本，能幫助這個庫讓更多人了解铸磅，更多的人用赡矢，可以說好的文檔就是一個門面。
有好的 README 文檔的項目不一定是一個好開源項目阅仔，但一個好開源項目一定有一個好的 README吹散。
下面就簡單的總結一下README文檔規(guī)范寫法。（這只是我個人根據(jù)github上幾百個大型開源庫總結出來的霎槐，如你有更好的意見，歡迎留言梦谜。）
一丘跌、README文檔的組成部分
看過很多開源框架的README文檔，綜合一下唁桩，大概有以下幾部分組成：
- （一）國際化
- （二）項目工程介紹
- （三）項目的使用效果圖
- （四）項目特點
- （五）項目的基本結構（架構）
- （六）集成方式
- （七）使用方法
- （八）混淆
- （九）關于作者/組織及交流方式等信息闭树。
- （十）貢獻者/貢獻組織
- （十一）鳴謝
- （十二）版權信息
二、下面就每個部分簡單的分析一下：
（一）國際化
github是面向全球的一個開源網(wǎng)站荒澡，所以不要局限于中文文檔报辱，建議寫一個英文的README，讓來自全球的人都能更方便的了解你的項目单山。推薦寫法碍现，在REAMDE開頭寫上國際化引用地址：
比如：
（二）項目工程介紹
項目介紹是必不可少的，它能讓別人快速了解項目米奸。項目介紹主要包括：
- 項目名稱昼接、logo（沒有l(wèi)ogo就不寫）
- 這個開源項目是做什么的？
- 這個項目是什么語言編寫的悴晰？
- 這個項目目前被多少人用到了慢睡，有多少好評等铡溪？
- 項目維護棕硫、依賴更新狀態(tài)（如果有的話哈扮，這也可以用）等
- 項目可用版本及其他版本，以及每個版本的更新信息記錄
- Demo 或官網(wǎng)地址（如果有）
效果圖如下所示：
英文版：
中文版：
- 上述案例里面那些圖標，請參考這個網(wǎng)站 Shields.io实檀，打開之后想用哪個直接復制就可以了膳犹，同時它也支持自定義樣式须床。
（三） 項目的使用效果圖
如果是一些自定義控件或者項目的演示效果的豺旬，基本都會放上演示效果圖柒凉，可以是圖片膝捞，也可以是gif圖。
建議：靜態(tài)的頁面的放截圖鲤遥，交互很復雜的建議放gif圖林艘。 如果功能比較多，建議每個功能一張效果圖卜朗。
示例如下：
LoveHeartView使用示意圖如下圖所示：
（四）項目特點
主要是介紹項目的特點，方便別人查看和了解該項目逛万。
比如 360的RePlugin框架的特點就寫的很詳細：
（五）項目的基本結構（架構）
這里主要介紹項目的各個組成部分得封，如果是框架忙上，可以附帶架構圖解疫粥；如果是其他的梗逮，可以提供一些UML分析圖绣溜，順便分析一下源碼也行的慷彤。
比如 360的RePlugin架構圖解 如下所示：
（六）集成方式
一般的項目傳到jcenter上面或者AS插件傳到jetbrains的話 一般會附帶相關的集成方式的說明怖喻。（如果沒有這些措施的話，這一步可以略過不看罢防。）
比如 okhttp 就有詳細的3種集成方式：
一個是下載Jar包唉侄；一個是引用Maven庫咒吐；第三個是添加Gradle依賴：
（七）使用方法
一般的README必不可少的，最重要的就是用法属划，主要包括：安裝恬叹，運行同眯，編譯须蜗，部署硅确，debug柿估，該github上的這個庫如何在自己的項目中使用循未，以及需要注意的問題绣檬，版本更新適配問題等等。
這里就拿 Glide 舉例說明嫂粟，Glide里面有一個詳細的wiki使用文檔的娇未，首頁的README里面也寫了一個簡單的基本用法，如下圖所示：
（八）混淆
一般來說赋元，開源庫都會設置一些混淆規(guī)則的忘蟹，部分項目由于項目類型特殊之處，所以就沒有混淆這一項搁凸，具體的看開源項目來定媚值。
例如LitePal這個開源庫的混淆 如下圖所示：
（九）關于作者/組織及交流方式等信息。
這個就很靈活了护糖，不是每一個必備褥芒，當然寫出來方便大家聯(lián)系作者，也是很好的嫡良∶谭觯可以寫一下作者或者組織的聯(lián)系方式，微信寝受，郵箱坷牛，博客，微博很澄，甚至支付寶轉賬二維碼等都是可以放上去的京闰。
例如 blankj的AndroidUtilCode這個庫為例，為了避免打廣告嫌疑甩苛，我做了打碼處理：
（十）貢獻者/貢獻組織
比如 谷歌推出的 sample 里面就有貢獻者/貢獻組織信息蹂楣，如下圖所示：
（十一）鳴謝
這個主要是引用了哪些開源技術，這里可以做一些鳴謝讯蒲，表示對別人的尊重痊土，其實也是一個引用聲明，避免因為版權而引起不必要的糾紛墨林。
例如：我寫的這個庫 https://github.com/AweiLoveAndroid/CommonDevKnowledge/blob/master/interview/summary.md 里面就寫了鳴謝赁酝。
（十二）版權信息
版本很重要，開源許可證很重要旭等，如果沒有生命版權酌呆，可能會因為一些侵權行為而無法很好的維權，版權信息可以保護作者的權益（個人理解）辆雾。
世界上的開源許可證肪笋，大概有上百種。很少有人搞得清楚它們的區(qū)別。最流行的有六種：GPL藤乙、BSD猜揪、MIT、Mozilla坛梁、Apache而姐、LGPL
烏克蘭程序員Paul Bagwell，畫了一張分析圖划咐，說明應該怎么選擇拴念。這是我見過的最簡單的講解，只用兩分鐘褐缠，你就能搞清楚這 六種許可證之間的最大區(qū)別政鼠。
比如 Picasso 里面的版權信息，如下圖所示：
