如何寫一個高逼格 README

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

編寫一個項目的 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 文檔

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

這些只是我在作一些文檔工做的時候，查看了挺多的文檔，綜合感想，寫了這麼多，可是實際狀況可能會大有不一樣，因此具體是否是要這麼寫，你們見仁見智啦！