Read Me文件的意義在于說明Source Code 做了什么? 運行在什么樣環境下? 如何查看編輯代碼? 其目的在于向使用者說明源碼有一個概覽情況的介紹. 至少要說明如下幾個問題:

這份源碼是用來做什么的?

如何去使用?

項目中重要的文件和子目錄的結構信息?

那如何編寫一個合格的ReadMe文檔.一個合格的ReadMe文檔應該包含哪些具體的信息?如下:

整個項目的介紹[說明創建項目意圖或是解決問題等]

指出開發者編譯整個項目需要的系統環境參數.并之處項目可能潛在的移植性問題.

當前項目中重要的文件和子目錄的結構信息.[必須]

項目更多資源支持站點或是版本更新包獲取所在的URL地址

編譯或安裝步驟說明.或是知名這些信息所在的文件名[類似GitHub則把版本情況放在Version單獨文件中等做法 通常應該Install文件]

一般國外開源項目為了附屬上源作者版權信息.會在該文檔中注明項目主持人和參與者的名單列表.或是列出該信息所在文件[通常為Credits文件]

關于本項目的版本更新或當前項目進展現在等信息.或支持包含該信息的文件[通常為NEWS文件]

如上為關于一個關于ReadMe應該包含內容.其中也包含一定可選項.其實從GitHub做法來看.ReadMe內容非常有限.而是把這些內容信息分別規范在除了ReadMe之外其他一些獨立的文件中. 類似關于項目的版本信息.Github做法放在一個獨立的Version文件中.關于當前項目受權信息則是放在
LICENSE.txt
文件中.

如果采用這方式 這里有必要說明這些信息如何歸類方式以及文件命名的規范問題.這里有一個很重要的原則.

越是常見的項目類型，越是應該按照約定俗成來構建項目的目錄結構，盡量不要別出新裁.這些文件命名目的讓在SourceCode容易別人識別閱讀.這些文件名本身就在向讀者傳達許多信息。如果你遵照標準的命名規則就可以給那些探索者有價值得線索以便他們更好的理解你的意圖. 而不是創造一些大家不熟悉命名.增加閱讀障礙和難度.

那如何正確命名ReadMe之外項目說明文件?可以參考如下通用命名做法:

ReadMe或Read.Me 整個項目的結構信息說明.是分發是第一個需要閱讀的文件.

Install：配置、編譯或安裝該項目的說明信息.一般是對項目運行環境參數配置說明.

Credits：本項目所有參與者或貢獻者的姓名列表.

NEWS：本項目最近的一些新聞或進展的情況說明.

History：該項目的歷史發展一些或是版本記錄信息.

Copying：明確指出該項目使用許可證條款.通常采用
GNU
.

License：該項目許可證條款文件.

Manifest：項目結構所有的文件列表.

FAQ：以純文本格式關于項目常見問題的解答.

TAGS：為Emacs或VI準備的標記文件.

從上述命名可以看出全部大寫的文件時給他人閱讀的文檔.[其上全部都應該大寫.]而不是項目的一個組成部分.

這里特別說明一下.在開始分發時.對于可能在軟件編譯或是運行 修改等過程中可能經常碰到問題.最好統一放入FAQ文件中.針對一些其他沒有設計特殊問題.最好在FAQ文件指導用戶如何采用什么渠道向你反饋或溝通該問題.

如果你維護過一定規模的用戶群的項目.你一定會明白一個好的FAQ會減輕項目維護者幾個數量級的負擔.

另外在每次發布時都保留一個HISTORY文件和NEWS文件，并列明時間信息非常有好處。在所有其他文件中，這兩個文件可以讓你在遇到一些專利侵權法律問題時有所準備 [雖然這種情況至今還沒有發生過，不過最好還是有備無患].

編寫好的項目說明文檔.養成好的操作習慣也是一種職業素養. 細節雖小.但儼然是這些小細節才組成一個優秀高效DEV最基本元素.