論寫好項目文檔的重要性和方法。

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

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

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

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

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

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

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

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

特么的被鴿了！

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

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

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

他說：“我看了很多的項目，只有你的項目文檔上的鏈接，是可以直接訪問的。”

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

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

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

如何寫好文檔

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

直觀通俗

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

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

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

可體驗易上手

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

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

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

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

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

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

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

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

簡潔清晰

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

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

排版工整

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

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

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

答疑

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

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

易搜索

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

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

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

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

界面美觀

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

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

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

清新風(fēng)格：

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

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

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