[譯] 如何編寫友好的 README

寫在最前面：
最近陸續把工做中積累的vue組件開源，在寫組件的README的時候不知道該怎麼能寫得很友(bi)好(ge)一些，想起來以前看的這篇文件，很詳細的介紹了寫README的幾個方面，因此翻譯出來跟你們分享下，你們能夠根據各自的項目狀況來寫本身的README。

一個項目的README是很是重要的；別人看到你的開源項目的時候第一個看到的就是README，同時README也經常是項目惟一的文檔。你的README對於你的項目來講，就至關於一個公司的官方網站同樣，就像網站須要注意不少用戶體驗同樣，咱們的README也應該從用戶的角度出發。

這篇文章將告訴咱們如何寫一個友好的README-不論對於新手仍是對你項目很瞭解的人來講，這個README都會很是有幫助同時能夠知足開發者的需求。

咱們會利用一個叫作"Paddington"的虛擬的庫做爲例子，分部分來說解這些東西。讓咱們從頭開始吧。

項目標題

毫無疑問，一個網站最上面一部分應該用來展現最重要的信息。咱們能夠把這個原則放在咱們的README上。

因此什麼纔是最重要的東西呢？正如所起到的做用同樣，項目名字是很重要的。因此咱們先加上下面這些內容：

上面這個基本能夠知足新用戶的需求，可是README的頭部也須要知足已存在的用戶的需求，他們有一些很容易回答的問題。當我訪問一個我很熟悉的項目的時候，我會想知道：

• 最新的版本的多少？

• 它構建經過了嗎？

做爲一個新用戶，我也有一些容易回答的問題：

• 它是用什麼語言寫的？

• 它支持哪一個語言版本？

• 它是否經過測試？

• 它採用哪一種開源證書？

咱們能夠經過徽章來回答上面全部的問題！

我在項目描述下面加了一行徽章，單獨一行不會佔據很大的空間同時又能涵蓋許多信息：

是否是很好看？我使用了一個叫作shields.io的服務，它提供了一致的徽章圖標同時也提供了一個添加自定義徽章的方式，好比開源證書信息。

對於頭部的最後一部分，若是項目足夠簡單的話，咱們能夠添加一個簡單的例子。這對於新手理解你的項目是用來幹什麼的有很大幫助，就像項目描述同樣。

咱們在頭部有限的空間裏面涵蓋了豐富的內容。好極了！如今咱們須要看看一些更具體的問題。若是咱們的README會變得很長，那麼要導航到某個具體的內容就變得很困難，如今添加一個目錄就變得頗有意義。

目錄

目錄對於相對比較短的README來講也是頗有用的。它解決了信息索引的需求，爲用戶提供了一些有幫助的跳轉連接到文檔的不一樣部分。

若是用戶只想要看看使用說明，爲何要讓他們滾動頁面看到他並不須要的安裝指南呢，更況且安裝指南只有第一次使用項目的時候會用到。

必要條件

如今咱們來到文檔中對於新用戶更有用的部分，咱們要確保他們獲取他們所須要的信息。這部分就是用來添加全部你項目的必要條件的地方：語言，語言版本，包管理工具，操做系統。

這些內容能夠直接寫上去或者經過列表來展現，明顯列表更清晰一些。這對你來講也頗有用，這能夠幫你有效的減小由於缺乏必要條件而提交的ISSUE的數量。

在寫必要條件的時候，你應該假設從0基礎開始使用你的項目。確保你添加了語言和包管理工具的相關連接，這樣你也許能幫助到對於項目一無所知的新手。

用法

你的使用手冊多是你README中最重要的部分，若是沒有這個不多人能夠知道怎麼用你的項目。

這部分能夠用不少種方式來寫，這取決於你項目的類型。你也許須要一個API手冊，一個web接口或者一個命令行工具；有時須要不僅一種。下面這個手冊涉及到一個Javascript API，不過你能夠把這個方式應用到其餘的接口文檔上。

首先咱們須要提到如何獲取代碼，是經過clone代碼仍是利用包管理工具來安裝。別忘了添加一些有用的連接，來提供一些便利。

當給一個API寫文檔的時候，儘可能保持簡單清晰。也就是說先寫出接口的主要用例。這能夠吸引第一次看的用戶。在這個例子中，咱們突出了方法的參數和返回類型，並附上的例子。越明確，就能給你減小越多的麻煩。

咱們已經涵蓋了咱們的主要用例，同時指明一些邊界用例以及用戶在使用過程當中會遇到的問題也是頗有幫助的。這個能夠做爲使用手冊的子章節放在使用手冊的最後。試着包括一些有問題的用戶會搜索的關鍵詞。

貢獻

這部分也是很重要的，這決定了是否會有用戶來給你貢獻代碼。就算你有一個CONTRIBUTING文件，若是一我的沒有Github或者開源的經驗就很難找到它。這部分應該包括基本信息而且若是你有一個CONTRIBUTING文件應該加上一個連接。

增長一個關於如何運行測試和提交pull request的簡單介紹，對你來講也頗有用。這意味着你review pull request的過程會更加有效率。

支持和版本變化

一個關於項目支持狀態的章節也是頗有用的，特別是當你發佈了不少個不一樣的主版本的時候。這部分對於一些要進行版本遷移的老用戶來講很是有幫助。

一個完整的遷移指南對於README來講可能太長了，因此我在項目中加入了一個MIGRATION文件，同時在README中添加了連接。

若是你有一個對於老版本的支持計劃，請突出他們。同時你也能夠用一個簡單的表格來列出主要的版本和他們支持的最後期限。

證書

最後你應該加一個版權信息以及一個項目所使用開源證書的連接。若是沒有這些信息不少用戶沒法使用你的項目，特別是一些大企業。就算你的項目裏面有一個LICENSE文件，添加一個證書的連接也是頗有用的。

其餘部分

咱們上面介紹的內容並無包括了README能夠寫的所有內容。我項目中還包括了其餘內容包括：

+ 爲何？

若是你的項目作了一些其餘項目已經作了的事情，或者特別複雜，提供一些解釋也是頗有幫助的。

+ 共有的問題

一個用來列出常常出現的問題的地方，能夠減小重複打開的ISSUE。

+ 例子

一個指向例子的連接。

+ 變動日誌

一個關於項目變動日誌的描述。

一個完整的 README

如今咱們已經擁有一個友好的README，你能夠在這裏看到全部內容。

我但願更多的人在寫文檔的時候能夠考慮用戶的需求，若是你以爲漏了什麼請告訴我。我對於如何寫好README的建議和想法很感興趣。

---

原文地址：http://rowanmanning.com/posts/writing-a-friendly-readme/
博客地址：Bin Playground