最近一個專案從程式設計師變成了一個高階文件哥，好吧，我還稱不上高階，但是我發現寫文件真不是一件容易的事情，要怎麼寫的讓人看的舒服、巴適、爽的不行，看完就想給你個贊呢？我也總結了一下寫文件的一些感想，也不能說是經驗，畢竟小弟還年輕，哈哈。

編寫一個專案的 README 就像是寫一本書的序言一樣，一個好的專案不應該僅僅只有一份高質量程式碼，同時更應該有一份高質量的文件。而對使用者來說，一份好的文件能夠節省大量的時間。

國際化

要知道比如 GitHub 這樣的程式碼託管平臺，可是有著另一個名字，全世界最大的同性交友網站（技術基不說話），你的專案可能不止中國的程式猿在使用，一個好的專案，使用者來自世界各地，那麼一份中英雙語的文件至關重要。

畢竟對母語的文件有更加親和的感覺，同時閱讀起來會更加順暢。

比如，Ant Design Pro 的文件：

專案是幹什麼的

首先，要有一個專案名，不一定要霸氣，但是一定要朗朗上口，不會讀起來很拗口，而且別太長。

比如說，chalk、react、vue、commander 等等。如果自己實在不知道怎麼起，搞個隨機函式，試試自己的運氣吧。

當然了，如果你有 LOGO 是最好的了，一張高清大圖 LOGO 帥一臉，看起來就舒服有木有。

就比如說這樣：

或者這樣：

再接下來，一個好的專案簡介，能夠幫助使用者瞭解他能夠使用這個工具幹什麼，能不能滿足自己的需求。一般來說，我們希望從簡介中，瞭解下面一些資訊：

• 什麼語言寫的？Node、Python 還是其他什麼
• 這個專案的用途是什麼
• 最新版本資訊
• 構建、測試結果等資訊
• Demo 演示地址或者官網

就像這樣：

對於我們技術 README 一定要各種徽章砸臉上，比如標配的 travis、coverage、npm 等等，給人一種安全感，如果你自己測試構建都沒過，我用著也不放心。至於這些東西大家可以去這兒看看：shield.io

同時，我們要精要的總結專案的閃光點，有哪些特性是激動人心的，別人沒有的，這是吸引使用者的好方法。

比如這樣：

安裝及快速開始

這部分內容是是文件很重要的部分，通過這些步驟，能夠讓使用者快速的使用。

首先，你要告訴使用者怎麼去獲取以及初始化專案，比如下面這樣：

然後你需要給一個簡單的例子，讓使用者快速感受到使用它的好處：

當然了，在這個地方，最好最直觀的方法就是放一張 gif 的圖片，吸引使用者的注意力，同時給使用者展示使用結果，比如這樣：

API

API 是一個專案的靈魂，這是暴露給使用者最直接的地方，當使用者有疑問的時候，他會第一時間去找你的 API 文件。

對於一個 API 應該表述清楚的是：

• 作用
• 入參及每個引數是否必須，資料型別是什麼等等
• 返回值

如果你的 API 不多，那麼可以放在一個檔案裡，但是如果你的 API 非常多，那麼建議你將 API 單獨放到一個檔案裡，這個檔案留一個連結就可以。

同時，如果你的 API 有相當多個版本，那麼需要準備幾份 API 文件，應對不同的需求。

就比如這樣：

版本變化

還有最好是能有一份 CHANGELOG 文件，對不同版本做了哪些修改，有什麼特性等等，讓使用者知道每個版本幹了什麼。

就比如這樣：

FAQ

當然了，如果你不想回答一些非常重複的問題，我想你需要一份 FAQ 來記錄一些常見問題。

貢獻

我相信很多人跟我一樣，能給一些知名倉庫提交 PR 是一件比較自豪的事情。

所以如果能提供一個提交 PR 的方式或者是途徑，能夠吸引更多的人來貢獻程式碼，同時將貢獻者，展示出來，我想會有更多人願意貢獻出自己的力量。

比如在這樣的列表中也是挺有意思的：

版權

相信前不久 Facebook 的開源協議事件大家都知道，也是鬧得沸沸揚揚，所以，對於開源協議等等的版權問題一定要慎重，如果你想做的不是一個玩具專案，那麼關於這塊一定要寫清楚。

總結

最後，總結一下，對於一份好的 README 來說，這些也許夠了，也許不夠，但是，文件始終是因為使用者才存在的東西，所以使用者關注什麼，什麼才是我們文件的重點。

但是這些基礎是我們應該都需要的：

• 名字
• 簡介
• 功能
• 安裝配置
• 快速教程
• API 文件

這些是使用者都會去關心的點，應該在編寫之前好好斟酌。

這些只是我在做一些文件工作的時候，查看了挺多的文件，綜合感想，寫了這麼多，但是實際情況可能會大有不同，所以具體是不是要這麼寫，大家見仁見智啦！

文 / 小烜同學天衣無縫的祕密是: 做技術，你快樂嗎？

編 / 熒聲

想要訂閱更多來自知道創宇開發一線的分享，請搜尋關注我們的微信公眾號：創宇前端（KnownsecFED）。歡迎留言討論，我們會盡可能回覆。

歡迎點贊、收藏、留言評論、轉發分享和打賞支援我們。打賞將被完全轉交給文章作者。

感謝您的閱讀。