README 文檔養成記

一般來講，當別人第一次接觸你的項目時，首先要看的必定是你的 README 文檔。所以，對你的項目來講， README 文檔的重要性不亞於一個公司的公司主頁。然而，愈來愈多的人正着力於優化網頁的用戶體驗，但卻鮮有人考慮將本身項目的 README 文件寫得易讀一些。

這篇文章就是爲改變現狀而生。它會指導你如何寫出一篇友好、易讀的 README ，從而知足廣大開發者及用戶的需求，使他們不管經驗多少都能很快上手。

在這篇文章中，咱們將虛構一個名叫「 Paddington 」的項目做爲例子，並分章節向你們介紹如何寫好一篇 README 文檔。

工程介紹

在 Web 領域，「頁面分界線」一直是讓人爭論不休的話題，許多網頁設計者爲了把他們認爲的用戶最想了解的全部信息放到網頁的頁面分界線以上（也就是俗稱的第一屏）而絞盡腦汁。對於一個好的 README 文檔來講也是如此，咱們必須把最重要的東西放到 README 文檔的「第一屏」。

那麼對於一個 README 文檔來講，什麼東西是最重要的呢？那確定是這個項目的名稱和主要的功能啦。那該怎麼寫呢？以下圖所示。
固然第一屏的內容大可能是爲從未接觸過該項目的人所準備的，可是 README 文檔的最開頭的幾行一樣要爲老用戶們服務。由於對於老用戶來講，他們一般想經過你的 README 文件瞭解一些常見問題，好比該項目的最新版本，或者是該項目是否還在繼續開發。

可是，若是做爲一個剛接觸這個項目的人，那麼除了上面的兩項，我還有相似如下的一些問題須要經過 README 文件瞭解：

• 這個項目是基於什麼語言編寫的

• 這個項目支持哪一個版本的語言規範

• 這個項目已經通過測試了麼

• 這個項目的許可類型是什麼

這些東西對於一個 README 文件來講也十分重要，可是若是將這些問題一古腦兒全都用文字敘述的方法放到 README 的前幾行，就會使 README 文檔看起來雜亂不堪。但還好，咱們有「標籤」這種神奇的東西。
如圖所示，我在項目簡介下面加了一行五光十色的標籤。這些標籤十分清晰的列出了幾乎全部咱們想知道的東西，同時又避免了純文字描述的枯燥和雜亂。

做爲 Heading 的最後一個部分，若是你的項目的功能能夠用一個簡單的例子來展現的話，那麼我建議你最好在標籤的下面加上這個例子。由於這一樣有助於新用戶快速瞭解你的項目能幹什麼。能夠說它跟上面的項目簡介具備同等重要的地位。
在上面的教程中，咱們用不多的篇幅清晰地完成了對項目的歸納。如今，全部人都能經過這小小几行字瞭解你的項目，咱們不得不說，幹得漂亮！

可是，一篇 README 要作的可不只僅是這些，接下來，咱們將面對用戶們在使用中可能遇到的更多，更具體的問題。固然，做爲一個 README 文件，咱們必須儘量周全的考慮到全部的問題並列出解決辦法，可是這樣無疑會使咱們的 README 文件變得「又臭又長」。一個明智的辦法即是創建目錄。

目錄

即便是在一個相對短的 README 中，目錄也是很是有用的。它簡化了信息的搜索，給用戶提供了一些快速跳轉到你文檔中的不一樣部分的連接。

若是用戶只是想看看幫助文檔，那他們就沒有必要先瀏覽一遍安裝指南。當用戶第一次接觸你的項目的時候，什麼纔是最有用的？

必要條件

咱們如今談論的將是對新用戶來講最有幫助的東西了，讓用戶獲取到他們真正須要的東西。在這裏，你能夠寫上任何你項目所須要的條件了。好比語言環境、語言版本、包管理系統、操做系統等。

只要能表達清楚，必要條件能夠以列表或散文的形式給出。這對本身也是有幫助的，這意味着將會出現更少的兼容性錯誤。

你應該假設用戶不具有任何的相關知識，確保所要求的語言和包管理工具都給出了連接。

使用方法

你的使用文檔多是你的 README 中最重要的部分了，卻少它的話不多人會經過閱讀你的代碼來學習如何使用。

首先咱們須要讓用戶知道如何獲取代碼，經過 Git 克隆或是包管理工具安裝。別忘了連接上任何有用的信息，以防用戶在拉取過程當中出現問題。

在提供 API 時，使之儘可能簡潔易用。換言之，把主要用例寫在前面。這保證了他人在第一次使用時注意點能更加集中。就咱們而言，咱們給出了方法所須要的參數及其返回的值，還有理想的用例。你表達的越清楚，遇到的問題就越少。

當咱們介紹完理想用法以後，列出用戶可能會遇到的問題以及一些邊界值也是至關有幫助的。這能夠是你文檔最後的一小部分，主要面向已經安裝並使用過你的項目的用戶。嘗試着解釋一些可能使用戶困惑或須要搜索的關鍵字。

貢獻

這一部分對於 README 文檔來講是很重要的，而且也是區分使用者和開發者的重要依據。即便你的項目中有一個 CONTRIBUTING 文檔，但若是你的使用者們沒有使用 Github 和開源項目的經驗的話，他們頗有可能找不到它。因此，本節除了包含一些基本內容以外，若是你的項目有一個 CONTRIBUTING 文檔，你須要在這裏放置它的連接。

你也能夠在此處舉例說明如何測試並生明 Pull Request 的正確格式。這將會使你的工程變得更加的規整有序。

若是你的項目有一個面向開發者的嚮導文檔，那麼你應該在這裏放置它的連接。這樣可使剛接觸你的項目的開發者感覺到莫大的方便，而且儘量保證因此的問題都會獲得解決。

兼容性和可移植性

在你的工程裏面兼容性仍是顯得很是重要的，尤爲是當你版本有了一些重要的更新時。這一部分對於如今正在使用你的項目並且急需升級指導的用戶們來講極其重要。

或許將一份詳細的移植指導寫進你的 README 文檔裏會顯得有些囉嗦，因此咱們能夠在咱們的項目根目錄中放置了一份 MIGRATION 文檔，而且在這裏放置了一個指向它的連接，方便有須要的用戶閱讀。（這裏是一個例子）

若是你打算兼容舊版本，你應該在這裏作出說明。你也能夠簡單地經過一個表格來講明他們的最終版本和中止支持日期。

版權

在 README 文件的最後你應該加上許可信息並添加一個指向具體許可文件的連接。若是沒有這部份內容，許多使用者，特別是大規模的企業級用戶將沒法使用你的工程。就算你將把 LICENSE 文件全都放在你的項目中，在這裏這個連接仍是顯得那麼有用。

其餘部分

這是一些有可能包含在你的 README 文件中部分。

爲何須要這些

當你的項目借用了其餘項目或者它的確很複雜時，在這裏提供一些有用的幫助信息非常頗有必要的。

常見問題

一些會被常常問到的問題

例子

獲取示例應用程序運行時的示例代碼或指針的連接

鳴謝

這部分是列出並感謝那些爲這個項目作出非技術性貢獻的人

更新日誌

這裏應該放置項目更新日誌的連接

如今咱們擁有一篇優秀的 README 文檔了!我但願更多的人在書寫文檔說明時可以考慮什麼纔是使用者所須要的，若有遺漏，歡迎提出意見。

 

Linux Story 小編舒適提示，更多詳情請訪問以下原文連接。

原文連接：http://rowanmanning.com/posts/writing-a-friendly-readme/

譯文連接：http://www.linuxstory.org/writing-a-friendly-readme/