Markdown 工程師也不簡單：如何寫一個高逼格 README
最近一個專案從程式員變成了一個高階文件哥，好吧，我還稱不上高階，但是我發現寫文件真不是一件容易的事情，要怎麼寫的讓人看的舒服、巴適、爽的不行，看完就想給你個贊呢？我也總結了一下寫文件的一些感想，也不能說是經驗，畢竟小弟還年輕，哈哈。
編寫一個專案的 README 就像是寫一本書的序言一樣，一個好的專案不應該僅僅只有一份高質量程式碼，同時更應該有一份高質量的文件。而對使用者來說，一份好的文件能夠節省大量的時間。
國際化
要知道比如 GitHub 這樣的程式碼託管平臺，可是有著另一個名字，全世界最大的同性交友網站（技術基不說話），你的專案可能不止中國的程式猿在使用，一個好的專案，使用者來自世界各地，那麼一份中英雙語的文件至關重要。
畢竟對母語的文件有更加親和的感覺，同時閱讀起來會更加順暢。
比如，Ant Design Pro 的文件：
專案是幹什麼的
首先，要有一個專案名，不一定要霸氣，但是一定要朗朗上口，不會讀起來很拗口，而且別太長。
比如說，chalk、react、vue、commander 等等。如果自己實在不知道怎麼起，搞個隨機函式，試試自己的運氣吧。
當然了，如果你有 LOGO 是最好的了，一張高清大圖 LOGO 帥一臉，看起來就舒服有木有。
就比如說這樣：
或者這樣：
再接下來，一個好的專案簡介，能夠幫助使用者瞭解他能夠使用這個工具幹什麼，能不能滿足自己的需求。一般來說，我們希望從簡介中，瞭解下面一些資訊：
- 什麼語言寫的？Node、Python 還是其他什麼
- 這個專案的用途是什麼
- 最新版本資訊
- 構建、測試結果等資訊
- Demo 演示地址或者官網
就像這樣：
對於我們技術 README 一定要各種徽章砸臉上，比如標配的 travis、coverage、npm 等等，給人一種安全感，如果你自己測試構建都沒過，我用著也不放心。至於這些東西大家可以去這兒看看： ofollow,noindex" target="_blank">shield.io
同時，我們要精要的總結專案的閃光點，有哪些特性是激動人心的，別人沒有的，這是吸引使用者的好方法。
比如這樣：
安裝及快速開始
這部分內容是是文件很重要的部分，通過這些步驟，能夠讓使用者快速的使用。
首先，你要告訴使用者怎麼去獲取以及初始化專案，比如下面這樣：
然後你需要給一個簡單的例子，讓使用者快速感受到使用它的好處：
當然了，在這個地方，最好最直觀的方法就是放一張 gif 的圖片，吸引使用者的注意力，同時給使用者展示使用結果，比如這樣：
API
API 是一個專案的靈魂，這是暴露給使用者最直接的地方，當使用者有疑問的時候，他會第一時間去找你的 API 文件。
對於一個 API 應該表述清楚的是：
- 作用
- 入參及每個引數是否必須，資料型別是什麼等等
- 返回值
如果你的 API 不多，那麼可以放在一個檔案裡，但是如果你的 API 非常多，那麼建議你將 API 單獨放到一個檔案裡，這個檔案留一個連結就可以。
同時，如果你的 API 有相當多個版本，那麼需要準備幾份 API 文件，應對不同的需求。
就比如這樣：
版本變化
還有最好是能有一份 CHANGELOG 文件，對不同版本做了哪些修改，有什麼特性等等，讓使用者知道每個版本幹了什麼。
就比如這樣：
FAQ
當然了，如果你不想回答一些非常重複的問題，我想你需要一份 FAQ 來記錄一些常見問題。
貢獻
我相信很多人跟我一樣，能給一些知名倉庫提交 PR 是一件比較自豪的事情。
所以如果能提供一個提交 PR 的方式或者是途徑，能夠吸引更多的人來貢獻程式碼，同時將貢獻者，展示出來，我想會有更多人願意貢獻出自己的力量。
比如在這樣的列表中也是挺有意思的：
版權
相信前不久 Facebook 的開源協議事件大家都知道，也是鬧得沸沸揚揚，所以，對於開源協議等等的版權問題一定要慎重，如果你想做的不是一個玩具專案，那麼關於這塊一定要寫清楚。
總結
最後，總結一下，對於一份好的 README 來說，這些也許夠了，也許不夠，但是，文件始終是因為使用者才存在的東西，所以使用者關注什麼，什麼才是我們文件的重點。
但是這些基礎是我們應該都需要的：
- 名字
- 簡介
- 功能
- 安裝配置
- 快速教程
- API 文件
這些是使用者都會去關心的點，應該在編寫之前好好斟酌。
這些只是我在做一些文件工作的時候，查看了挺多的文件，綜合感想，寫了這麼多，但是實際情況可能會大有不同，所以具體是不是要這麼寫，大家見仁見智啦！
文 / 小烜同學
天衣無縫的祕密是: 做技術，你快樂嗎？
編 / 熒聲
你可以 在 Github 關注本文作者 哦。
本文已由作者授權釋出，版權屬於創宇前端。歡迎註明出處轉載本文。本文連結： https://knownsec-fed.com/2018...
想要訂閱更多來自知道創宇開發一線的分享，請搜尋關注我們的微信公眾號：創宇前端（KnownsecFED）。歡迎留言討論，我們會盡可能回覆。
歡迎點贊、收藏、留言評論、轉發分享和打賞支援我們。打賞將被完全轉交給文章作者。
感謝您的閱讀。