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/

轉載請註明出處，否則必究相關責任。