我們在Github上創建項目的時候，常常會看到默認使用README文件初始化該項目，然後在新建項目的根目錄下就會生成README.md文件。

有好的README文檔的項目不一定是一個好的開源項目，但一個好開源項目一定有一個好的README

1. README文檔的組成部分

• （一）國際化
• （二）項目工程介紹
• （三）項目的使用效果圖
• （四）項目特點
• （五）項目的基本結構（架構）
• （六）集成方式
• （七）使用方法
• （八）混淆
• （九）關於作者/組織及交流方式等信息。
• （十）貢獻者/貢獻組織
• （十一）鳴謝
• （十二）版權信息

一）國際化

github是面向全球的一個開源網站，所以不要侷限於中文文檔，建議寫一個英文的README，讓來自全球的人都能更方便的瞭解你的項目。推薦寫法，在REAMDE開頭寫上國際化引用地址

（二）項目工程介紹

項目介紹是必不可少的，它能讓別人快速瞭解項目。項目介紹主要包括：

• 項目名稱、logo（沒有logo就不寫）
• 這個開源項目是做什麼的？
• 這個項目是什麼語言編寫的？
• 這個項目目前被多少人用到了，有多少好評等？
• 項目維護、依賴更新狀態（如果有的話，這也可以用）等
• 項目可用版本及其他版本，以及每個版本的更新信息記錄
• Demo 或官網地址（如果有）

上述案例裏面那些圖標，請參考這個網站 Shields.io，打開之後想用哪個直接複製就可以了，同時它也支持自定義樣式。

（三） 項目的使用效果圖

如果是一些自定義控件或者項目的演示效果的，基本都會放上演示效果圖，可以是圖片，也可以是gif圖。
建議：靜態的頁面的放截圖，交互很複雜的建議放gif圖。 如果功能比較多，建議每個功能一張效果圖。

（四）項目特點

主要是介紹項目的特點，方便別人查看和了解該項目。

（五）項目的基本結構（架構）

這裏主要介紹項目的各個組成部分，如果是框架，可以附帶架構圖解；如果是其他的，可以提供一些UML分析圖，順便分析一下源碼也行的。

（六）集成方式

一般的項目傳到jcenter上面或者AS插件傳到jetbrains的話 一般會附帶相關的集成方式的說明。（如果沒有這些措施的話，這一步可以略過不看。）

（七）使用方法

一般的README必不可少的，最重要的就是用法，主要包括：安裝，運行，編譯，部署，debug，該github上的這個庫如何在自己的項目中使用，以及需要注意的問題，版本更新適配問題等等。

（八）混淆

一般來說，開源庫都會設置一些混淆規則的，部分項目由於項目類型特殊之處，所以就沒有混淆這一項，具體的看開源項目來定。

（九）關於作者/組織及交流方式等信息。

這個就很靈活了，不是每一個必備，當然寫出來方便大家聯繫作者，也是很好的。可以寫一下作者或者組織的聯繫方式，微信，郵箱，博客，微博，甚至支付寶轉賬二維碼等都是可以放上去的。

（十）貢獻者/貢獻組織

比如 谷歌推出的 sample 裏面就有貢獻者/貢獻組織信息

（十一）鳴謝

這個主要是引用了哪些開源技術，這裏可以做一些鳴謝，表示對別人的尊重，其實也是一個引用聲明，避免因爲版權而引起不必要的糾紛。

（十二）版權信息

版本很重要，開源許可證很重要，如果沒有生命版權，可能會因爲一些侵權行爲而無法很好的維權，版權信息可以保護作者的權益（個人理解）。

世界上的開源許可證，大概有上百種。很少有人搞得清楚它們的區別。最流行的有六種：GPL、BSD、MIT、Mozilla、Apache、LGPL

烏克蘭程序員Paul Bagwell，畫了一張分析圖，說明應該怎麼選擇。這是我見過的最簡單的講解，只用兩分鐘，你就能搞清楚這 六種許可證之間的最大區別。

2. 優秀的README文檔應該包含哪些內容？

1. 項目描述

2. 如何運行

3. 業務介紹

4. 項目備註

每一項都有哪些作用？

• 項目描述

  需要說明我們的項目名，項目功能簡述，代碼倉庫地址，以及該項目的第一負責人。誰交接給我們的項目，誰就是該項目的第一負責人。

• 如何運行

  開發環境配置。一般是我們需要的一些運行環境配置。

  開發&發佈 命令。我們怎麼通過命令開啓本地開發，以及構建發佈。

  代理配置。如果我們的項目在本地開發時需要用到一些代理工具，例如fiddler或whistle等，我們需要列出代理的配置項。最好是直接導出一個代理配置的文件，放在項目下

  發佈。如果我們有用到一些發佈平臺，最好貼上項目的發佈模塊和發佈單，減少我們發佈的時間成本。

  錯誤告警及監控。相信我們平常都會對線上的項目部署錯誤告警和監控日誌的服務，方便我們及時排查現網問題，這裏我們可以加入項目的一些監控屬性ID

  接口API。這裏我們需要貼入項目中拉去的後臺接口地址以及描述，還有我們的接口負責人，當後臺服務異常，可以直接聯繫到後臺同學。

  數據上報。我們在平常項目裏都有加入一些數據上報，給產品同學統計業務數據用，這裏我們最好闡述下都有哪些數據的上報。如果上報出問題，產品妹子找過來，我們不至於是一臉懵逼。

• 業務介紹

  對於前端來說，我們一個項目可能不止一個頁面，那麼我們需要給出以下信息:

  業務入口地址及渠道鏈接 即我們整個項目的入口頁面，或者比較重要的頁面地址。一般入口頁面，我們可能會在多個渠道進行投放，那麼需要列出所有的渠道鏈接

• 各頁面及描述 列出我們項目內的所有頁面信息，比如下面這樣：

  頁面目錄	頁面描述	頁面鏈接	參數描述
  index	首頁	https://xxx.com	無

• 項目備註 項目中需要告訴其他開發者一些關鍵信息，比如我們頁面打包構建，需要注意哪些問題等等，這些信息雖然不是必須的，但是可以幫助其他開發者降低開發的風險成本。

3. 一個有逼格的README應有的樣子

項目名稱

這裏再寫一句騷氣又精準的話描述你的項目吧。

上手指南

寫幾句這樣的話概括接下來的內容：以下指南將幫助你在本地機器上安裝和運行該項目，進行開發和測試。關於如何將該項目部署到在線環境，請參考部署小節。

安裝要求

列出運行該項目必須要具備的條件以及必須要安裝的軟件，最好給出具體的安裝步驟。

1. 必須安裝我
2. 我也必須安裝
3. 安裝我也是必須的

安裝步驟

一步一步地說明怎麼去搭建環境，怎麼讓項目跑起來。

首先你需要

1. 幹這件事
2. 幹那件事
3. 繼續幹這件事
   …一直到完成。

最後闡述安裝完成後的情況，展示下Demo

測試

解釋說明一下如何運行該系統的自動測試部分。

分解爲端對端測試

解釋這些測試是什麼以及爲什麼要做這些測試
1.我是個栗子
2.我也是個栗子
3.我是栗子的哥哥

代碼風格測試

解釋這些測試是什麼以及爲什麼要做這些測試
1.我是個栗子
2.我也是個栗子
3.我是栗子的哥哥

部署

對以上的安裝步驟進行補充說明，描述如何在在線環境中安裝該項目。

使用到的框架

Dropwizard - Web框架
Maven - 依賴屬性管理
ROME - 生成RSS源

貢獻者

請閱讀***CONTRIBUTING.md*** 查閱爲該項目做出貢獻的開發者。

版本控制

該項目使用SemVer進行版本管理。您可以在repository參看當前可用版本。

作者

地球上的鹽味
您也可以在貢獻者名單中參看所有參與該項目的開發者。

版權說明

該項目簽署了MIT 授權許可，詳情請參閱 LICENSE.md

鳴謝

該項目參考了XXX的 XXX
靈感來源於XXX
感謝女友的支持和陪伴

以上。其實在實際的寫作當中，也並不一定要完全跟着這個框架來，可以根據項目情況進行增刪。比如稍微複雜點的項目，就要更多的緯度去說明，那麼在開頭就需要列出目錄（Table Of Content）。另外，圖片展示也是一種常用的手段，多放圖片，會讓你的文檔更有趣味。

如何寫一個優秀的GitHub項目README文檔？(其他比較好的參考文章)

https://www.cnblogs.com/shiyanlou/p/10312859.html

https://www.cnblogs.com/wj-1314/p/8547763.html