Markdown 工程师也不简单：如何写一个高逼格 README
編寫一個(gè)項(xiàng)目的 README 就像是寫一本書的序言一樣，一個(gè)好的項(xiàng)目不應(yīng)該僅僅只有一份高質(zhì)量代碼，同時(shí)更應(yīng)該有一份高質(zhì)量的文檔。而對(duì)使用者來(lái)說(shuō)，一份好的文檔能夠節(jié)省大量的時(shí)間。
國(guó)際化
要知道比如 GitHub 這樣的代碼托管平臺(tái)，可是有著另一個(gè)名字，全世界最大的同性交友網(wǎng)站（技術(shù)基不說(shuō)話），你的項(xiàng)目可能不止中國(guó)的程序猿在使用，一個(gè)好的項(xiàng)目，使用者來(lái)自世界各地，那么一份中英雙語(yǔ)的文檔至關(guān)重要。
畢竟對(duì)母語(yǔ)的文檔有更加親和的感覺(jué)，同時(shí)閱讀起來(lái)會(huì)更加順暢。
比如，Ant Design Pro 的文檔：
項(xiàng)目是干什么的
首先，要有一個(gè)項(xiàng)目名，不一定要霸氣，但是一定要朗朗上口，不會(huì)讀起來(lái)很拗口，而且別太長(zhǎng)。
比如說(shuō)，chalk、react、vue、commander 等等。如果自己實(shí)在不知道怎么起，搞個(gè)隨機(jī)函數(shù)，試試自己的運(yùn)氣吧。
當(dāng)然了，如果你有 LOGO 是最好的了，一張高清大圖 LOGO 帥一臉，看起來(lái)就舒服有木有。
就比如說(shuō)這樣：
或者這樣：
再接下來(lái)，一個(gè)好的項(xiàng)目簡(jiǎn)介，能夠幫助使用者了解他能夠使用這個(gè)工具干什么，能不能滿足自己的需求。一般來(lái)說(shuō)，我們希望從簡(jiǎn)介中，了解下面一些信息：
- 什么語(yǔ)言寫的？Node、Python 還是其他什么
- 這個(gè)項(xiàng)目的用途是什么
- 最新版本信息
- 構(gòu)建、測(cè)試結(jié)果等信息
- Demo 演示地址或者官網(wǎng)
就像這樣：
對(duì)于我們技術(shù) README 一定要各種徽章砸臉上，比如標(biāo)配的 travis、coverage、npm 等等，給人一種安全感，如果你自己測(cè)試構(gòu)建都沒(méi)過(guò)，我用著也不放心。至于這些東西大家可以去這兒看看：shield.io
同時(shí)，我們要精要的總結(jié)項(xiàng)目的閃光點(diǎn)，有哪些特性是激動(dòng)人心的，別人沒(méi)有的，這是吸引用戶的好方法。
比如這樣：
安裝及快速開始
這部分內(nèi)容是是文檔很重要的部分，通過(guò)這些步驟，能夠讓使用者快速的使用。
首先，你要告訴用戶怎么去獲取以及初始化項(xiàng)目，比如下面這樣：
然后你需要給一個(gè)簡(jiǎn)單的例子，讓使用者快速感受到使用它的好處：
當(dāng)然了，在這個(gè)地方，最好最直觀的方法就是放一張 gif 的圖片，吸引用戶的注意力，同時(shí)給用戶展示使用結(jié)果，比如這樣：
API
API 是一個(gè)項(xiàng)目的靈魂，這是暴露給用戶最直接的地方，當(dāng)使用者有疑問(wèn)的時(shí)候，他會(huì)第一時(shí)間去找你的 API 文檔。
對(duì)于一個(gè) API 應(yīng)該表述清楚的是：
- 作用
- 入?yún)⒓懊總€(gè)參數(shù)是否必須，數(shù)據(jù)類型是什么等等
- 返回值
如果你的 API 不多，那么可以放在一個(gè)文件里，但是如果你的 API 非常多，那么建議你將 API 單獨(dú)放到一個(gè)文件里，這個(gè)文件留一個(gè)鏈接就可以。
同時(shí)，如果你的 API 有相當(dāng)多個(gè)版本，那么需要準(zhǔn)備幾份 API 文檔，應(yīng)對(duì)不同的需求。
就比如這樣：
版本變化
還有最好是能有一份 CHANGELOG 文檔，對(duì)不同版本做了哪些修改，有什么特性等等，讓用戶知道每個(gè)版本干了什么。
就比如這樣：
FAQ
當(dāng)然了，如果你不想回答一些非常重復(fù)的問(wèn)題，我想你需要一份 FAQ 來(lái)記錄一些常見(jiàn)問(wèn)題。
貢獻(xiàn)
我相信很多人跟我一樣，能給一些知名倉(cāng)庫(kù)提交 PR 是一件比較自豪的事情。
所以如果能提供一個(gè)提交 PR 的方式或者是途徑，能夠吸引更多的人來(lái)貢獻(xiàn)代碼，同時(shí)將貢獻(xiàn)者，展示出來(lái)，我想會(huì)有更多人愿意貢獻(xiàn)出自己的力量。
比如在這樣的列表中也是挺有意思的：
版權(quán)
相信前不久 Facebook 的開源協(xié)議事件大家都知道，也是鬧得沸沸揚(yáng)揚(yáng)，所以，對(duì)于開源協(xié)議等等的版權(quán)問(wèn)題一定要慎重，如果你想做的不是一個(gè)玩具項(xiàng)目，那么關(guān)于這塊一定要寫清楚。
總結(jié)
最后，總結(jié)一下，對(duì)于一份好的 README 來(lái)說(shuō)，這些也許夠了，也許不夠，但是，文檔始終是因?yàn)槭褂谜卟糯嬖诘臇|西，所以使用者關(guān)注什么，什么才是我們文檔的重點(diǎn)。
但是這些基礎(chǔ)是我們應(yīng)該都需要的：
- 名字
- 簡(jiǎn)介
- 功能
- 安裝配置
- 快速教程
- API 文檔
這些是使用者都會(huì)去關(guān)心的點(diǎn)，應(yīng)該在編寫之前好好斟酌。
這些只是我在做一些文檔工作的時(shí)候，查看了挺多的文檔，綜合感想，寫了這么多，但是實(shí)際情況可能會(huì)大有不同，所以具體是不是要這么寫，大家見(jiàn)仁見(jiàn)智啦！
文 / 小烜同學(xué)
天衣無(wú)縫的秘密是: 做技術(shù)，你快樂(lè)嗎？
編 / 熒聲
你可以在 Github 關(guān)注本文作者哦。
本文已由作者授權(quán)發(fā)布，版權(quán)屬于創(chuàng)宇前端。歡迎注明出處轉(zhuǎn)載本文。本文鏈接：https://knownsec-fed.com/2018...
想要訂閱更多來(lái)自知道創(chuàng)宇開發(fā)一線的分享，請(qǐng)搜索關(guān)注我們的微信公眾號(hào)：創(chuàng)宇前端（KnownsecFED）。歡迎留言討論，我們會(huì)盡可能回復(fù)。
歡迎點(diǎn)贊、收藏、留言評(píng)論、轉(zhuǎn)發(fā)分享和打賞支持我們。打賞將被完全轉(zhuǎn)交給文章作者。
感謝您的閱讀。
總結(jié)
以上是生活随笔為你收集整理的Markdown 工程师也不简单：如何写一个高逼格 README的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： 洛谷 2585 [ZJOI2006]三色
- 下一篇： kylin与superset整合