論寫好項(xiàng)目文檔的重要性和方法。

還記得前段時(shí)間火遍全網(wǎng)的合成大西瓜游戲么？

其實(shí)當(dāng)我剛剛聽說這個(gè)游戲的時(shí)候，屬于村里剛剛通網(wǎng)，當(dāng)時(shí)這個(gè)游戲都已經(jīng)在網(wǎng)上傳遍了，而且也有同學(xué)扒光了源碼，并公開到了 GitHub 平臺。

正好當(dāng)時(shí)是午休，我就看了下這個(gè)游戲的源碼，發(fā)現(xiàn)做一些簡單的修改難度并不大。正好有同學(xué)在網(wǎng)上求修改的方法，索性我就認(rèn)認(rèn)真真地出了一個(gè)『 魔改大西瓜教程 』，并且也在 GitHub 上建了一個(gè)項(xiàng)目。

結(jié)果沒想到，很快這個(gè)項(xiàng)目就后來居上，霸占榜首！相關(guān)教程也在網(wǎng)上瘋傳，總閱讀量也有幾十萬！

值得一提的是，有一位 B 站的 百大 UP 主（粉絲 300w+）看到了我的項(xiàng)目后，主動(dòng)聯(lián)系我能否和他合作，為他的視頻提供技術(shù)支持。

作為一名 1024 線小 up，有機(jī)會和大佬合作，我是非常激動(dòng)的，當(dāng)晚我們就電話聯(lián)系，并且第二天幫他完成了需要的作品。

從那天之后，我就一直期待這位百大 up 發(fā)布這個(gè)視頻， 小小地提攜自己一筆。

結(jié)果，這一等，一直等到了游戲過氣，也沒看到視頻發(fā)出來。

特么的被鴿了！

不過我也沒覺得生氣，畢竟有圈層差距，在幾百萬粉的大佬眼里，這叫事兒么？

但還是感謝他，讓我明白了一個(gè)編程道理，那就是 寫好項(xiàng)目文檔的重要性。

我當(dāng)時(shí)問他，為什么網(wǎng)上這么多魔改大西瓜游戲的教程，我也不是最早發(fā)的，為什么偏偏選中了我呢？

他說：“我看了很多的項(xiàng)目，只有你的項(xiàng)目文檔上的鏈接，是可以直接訪問的?！?/p>

原來如此，是 “第一眼” 的作用！

現(xiàn)在網(wǎng)上的開源項(xiàng)目和產(chǎn)品太多了，如果想讓更多用戶使用你的項(xiàng)目，那一定要在 入口處 做足功夫。好的官網(wǎng)是公司產(chǎn)品的門面，同理，好的項(xiàng)目文檔也是一個(gè)項(xiàng)目的牌面。所以，在開發(fā)項(xiàng)目的過程中，要持續(xù)寫文檔。

那如何為項(xiàng)目提供一份優(yōu)質(zhì)的文檔呢？

如何寫好文檔

什么樣的文檔算得上優(yōu)質(zhì)呢？我總結(jié)了下面幾點(diǎn)，大家可以從這些角度來優(yōu)化項(xiàng)目文檔。

直觀通俗

如果是對外的項(xiàng)目文檔，建議在文檔的開頭用最通俗的方式來讓用戶理解你這個(gè)項(xiàng)目是做什么的，而不是一上來就用些過于專業(yè)的術(shù)語。盡量讓文檔內(nèi)容更直觀，能讓用戶一眼 get 到項(xiàng)目的價(jià)值是最好的。

比如可以在項(xiàng)目開頭加入一些統(tǒng)計(jì)小徽標(biāo)、列舉一些項(xiàng)目亮點(diǎn)圖片等，還可以用一些可視化圖表來代替繁雜的數(shù)據(jù)表格，幫助用戶更快地理解項(xiàng)目。

阿里 Ant Design 的項(xiàng)目文檔就很棒，大標(biāo)題下用一句話介紹了項(xiàng)目是什么，然后用大量小徽標(biāo)補(bǔ)充了項(xiàng)目的信息，并且放上了幾張美觀的組件截圖。大家可以參考一下。

可體驗(yàn)易上手

除了內(nèi)容要直觀通俗外，如果能在文檔中直接提供一個(gè)項(xiàng)目的在線體驗(yàn)地址，會給項(xiàng)目大大加分！

畢竟有很多同學(xué)相對于看文檔，更喜歡自己動(dòng)手體驗(yàn)。

除了體驗(yàn)鏈接外，如果是可運(yùn)行的項(xiàng)目，一定要提供快速運(yùn)行項(xiàng)目的方法，比如怎么搭建環(huán)境、怎么啟動(dòng)項(xiàng)目、設(shè)置哪些參數(shù)等?？梢栽偬峁┮粋€(gè)小 Demo，幫助用戶快速使用和學(xué)習(xí)項(xiàng)目。

對于后端項(xiàng)目，最好能夠提供一些在線的數(shù)據(jù)源，不需要用戶自己在本地搭建數(shù)據(jù)庫和造數(shù)據(jù)。

這一點(diǎn)，Ant Design 的文檔做的依然很好，提供了兩種安裝方式和簡單的組件用法：

如果是開源項(xiàng)目，可以在文檔中補(bǔ)充參與項(xiàng)目貢獻(xiàn)的方式，吸引更多朋友為你的項(xiàng)目做貢獻(xiàn)。

值得一提的是，現(xiàn)在很多云平臺都支持用戶一鍵部署項(xiàng)目，在文檔中補(bǔ)充這個(gè)功能，能讓用戶更方便地運(yùn)行你的項(xiàng)目，無需自己在本地搭建環(huán)境。

比如當(dāng)時(shí)我給魔改大西瓜項(xiàng)目文檔中添加了騰訊云一鍵部署按鈕，可以直接上線魔改網(wǎng)站！

簡潔清晰

一定要好好梳理下內(nèi)容的順序，盡量化繁為簡，還要?jiǎng)澐职鍓K，讓整個(gè)文檔更加結(jié)構(gòu)化，清晰又有條理。

如果項(xiàng)目文檔內(nèi)容較多，在文檔開頭，還要有明確的目錄或菜單引導(dǎo)。

排版工整

想要提高代碼的可讀性，就要對其進(jìn)行格式化。同理，寫文檔也講究排版和格式，統(tǒng)一的排版和規(guī)范的格式能夠提高文檔的可讀性，給用戶良好的體驗(yàn)。

網(wǎng)上有一份開源的『 中文文案排版指北 』，統(tǒng)一了中文文案、排版的相關(guān)用法，幫助你寫出優(yōu)雅的文檔，降低團(tuán)隊(duì)成員之間的溝通成本，增強(qiáng)網(wǎng)站氣質(zhì)。

比如中英文之間要添加空格、數(shù)字與單位之間需要增加空格等，文檔地址見文末。

答疑

如果很多用戶都對項(xiàng)目有相似的疑問，不妨在文檔中補(bǔ)充答疑（FAQ 經(jīng)常被問的問題），整理些常見的問題供用戶自己參考。可以降低團(tuán)隊(duì)維護(hù)項(xiàng)目的成本，并且也讓用戶明白，這個(gè)項(xiàng)目的負(fù)責(zé)人非常貼心，值得信賴！

我在維護(hù)魔改大西瓜項(xiàng)目時(shí)，基本每天都有數(shù)百個(gè)問題，如果不采用這種方式，挨個(gè)回答問題，一天可能都回答不完！

易搜索

文檔內(nèi)容較多時(shí)，如果提供全文搜索功能，可以幫助讀者更快找到自己的感興趣內(nèi)容。

現(xiàn)在有很多的文檔站點(diǎn)生成工具，只要將寫好的文檔放到工具目錄下，就能自動(dòng)給你生成一個(gè)支持搜索的網(wǎng)站，還可以發(fā)布到服務(wù)器上供其他人公開訪問！

常用的文檔站點(diǎn)生成工具有：Docsify、VuePress、Docusaurus、Dumi 等。

用法很簡單，可以參考這篇文章：實(shí)戰(zhàn) | docsify+云開發(fā)，高效創(chuàng)造你的文檔網(wǎng)站

界面美觀

文檔的內(nèi)容很重要，但也要保證文檔頁面的美觀，否則也會影響用戶的閱讀體驗(yàn)和效率。

比如下面兩種風(fēng)格的文檔，我會更傾向于后者的界面風(fēng)格。

經(jīng)典風(fēng)格：

清新風(fēng)格：

通常也不需要我們自己來設(shè)計(jì)和開發(fā)文檔的界面，大部分平臺都提供了默認(rèn)樣式。也可以用上面提到的文檔站點(diǎn)生成工具，選用工具提供的主題，或者自定義文檔界面。

最后，通過這件事，我還明白了一點(diǎn)：成功的路上沒有捷徑，還是要靠自己啊！

優(yōu)雅排版文檔：https://www.code-nav.cn/rd/?rid=28ee4e3e607167fa0ecab6b722c458d7