程序員如何編寫高大上且實用的技術(shù)文檔

時間：2023-05-16 20:42:02 | 來源：網(wǎng)站運營

時間：2023-05-16 20:42:02 來源：網(wǎng)站運營

程序員如何編寫高大上且實用的技術(shù)文檔：

如何編寫高大上的技術(shù)文檔

作為程序員，除了會寫代碼，能查bug，還要會畫圖（UML建模）、做PPT（分享、述職等），更重要的是還要能寫得出文檔，并且能寫出高大上的文檔。

根據(jù)過往的經(jīng)驗，技術(shù)文檔一般會：

項目文檔：用于開啟新項目的整體概要文檔，說明項目背景、成員、依賴關(guān)系、項目整體排期、里程碑等信息。

部署文檔：介紹網(wǎng)站或系統(tǒng)如何進(jìn)行部署，搭建運行環(huán)境，通常需要說明代碼的Git倉庫位置、數(shù)據(jù)庫結(jié)構(gòu)、Nginx/Apache配置、計劃任務(wù)配置、其他配置，是否需要CDN或HTTPS等，以及注意事項。

接口文檔：針對每個API接口提供的文檔，說明接口地址，調(diào)用方式，接口參數(shù)，返回結(jié)構(gòu)，異常情況等。

模板文檔：提供給前端使用的模板文檔，說明每個網(wǎng)站頁面會存在哪些變量、類型是什么、以及處理邏輯，方便前端進(jìn)行渲染、展示和交互。

設(shè)計文檔：針對系統(tǒng)、子系統(tǒng)或某個功能模塊的設(shè)計說明，從技術(shù)架構(gòu)到軟件設(shè)計，到數(shù)據(jù)庫建模，以及核心技術(shù)的介紹，性能分析等，面向?qū)ο笫窍嗤瑢I(yè)的專業(yè)人員。

開發(fā)文檔：針對每個開發(fā)需求而編寫的文檔，說明需求的背景、當(dāng)前需求的實現(xiàn)思路，并記錄這個需求所產(chǎn)生的接口文檔、模板文檔、數(shù)據(jù)庫變更、上線待辦清單、代碼倉庫和相應(yīng)的開發(fā)分支，以及一些注意事項，方便需求在開發(fā)過程中，以及在測試聯(lián)調(diào)過程中，有很好的文檔進(jìn)行備忘、溝通和回顧。如果有依賴底層或第三方的接口，也應(yīng)一并補充。若有外部調(diào)用方，也應(yīng)進(jìn)行登記。

故障文檔：當(dāng)出現(xiàn)線上故障時，處理完畢后，應(yīng)編寫故障復(fù)盤文檔，進(jìn)行原因分析、思考改進(jìn)措施、貼出關(guān)鍵的代碼、交待故障發(fā)生以及處理的歷史過程，方便團(tuán)隊進(jìn)行回顧、學(xué)習(xí)和避免類似問題再次發(fā)生。

分享文檔：對新技術(shù)或已有技術(shù)的技術(shù)分享，例如：如何利用docker部署本地開發(fā)環(huán)境。

新人文檔：為新加入團(tuán)隊成員而編寫的新人指引教程，包括系統(tǒng)介紹、應(yīng)該開通哪些賬號、遇到的一些常見問題、入周第一周應(yīng)該做什么等。

除此之外，還有系統(tǒng)負(fù)責(zé)人文檔、數(shù)據(jù)庫文檔、版本文檔、需求文檔等，不一一列出。

文檔編寫的要點

切記，編寫文檔的目的是為了讓讀者可以快速有效地獲取他想知道的信息。

因此，文檔編寫規(guī)則第一條：要簡單、清晰、明了。不要為了湊字?jǐn)?shù)而堆字?jǐn)?shù)。

文檔編寫第二條：明確文檔面向的讀者和受眾。根據(jù)所編寫的文檔，判斷主要面向的受眾是產(chǎn)品、技術(shù)、測試還是商務(wù)人員，盡量使用他們所能理解和熟悉的詞匯和表達(dá)方式來表達(dá)。

文檔編寫第三條：提供必要的信息。根據(jù)需要編寫的技術(shù)類型，提供必要的信息，就像攝影拍照一樣，有一些約定的攝影構(gòu)圖，例如：均衡式構(gòu)圖、對稱式構(gòu)圖、對角線構(gòu)圖、三角形構(gòu)圖、九宮格構(gòu)圖等。文檔也是一樣，不同文檔需要包含的元素、標(biāo)題和部分也有所不同。然后當(dāng)你熟悉 后，可靈活安排文檔的內(nèi)容，以最為恰當(dāng)?shù)慕Y(jié)構(gòu)形式來表達(dá)。

文檔編寫第四條：排版與圖片。盡量不要一味地只提供文字信息，這樣會讓讀者看起來很壓抑而且覺得是“天書”。應(yīng)該適當(dāng)留一些空行，讓讀者眼睛“休息”下，對讀者友好一些。同時，提供一些代碼片段、UML圖片或相關(guān)的插圖用于輔助說明。補充一些參考的文獻(xiàn)和資料。排版上，進(jìn)行分段，分章節(jié)部分，注意對重要的信息高亮、加粗、或重復(fù)說明。

文檔編寫第五條：萬事開頭難。很多技術(shù)人員覺得編寫文檔比寫代碼還要難，還要頭疼。其實寫文檔和寫代碼是類似的，很難一開始就寫出完美的文檔。應(yīng)該是像寫代碼一樣，一開始寫得很丑陋，但沒關(guān)系，至少有內(nèi)容了。然后，可以不斷重構(gòu)文檔，對缺少的信息補全，對多余的信息進(jìn)行刪除。最后覺得內(nèi)容上OK的話，就可以再進(jìn)行排版和修飾，補充一些圖片。慢慢的，在通過用心花時間后，你的完美文檔就慢慢出來了。

使用主流的markdown格式進(jìn)行文檔編寫

首先，向小白程序員介紹一下markdown這種格式。這是一種很主流的格式，Markdown是一種可以使用普通文本編輯器編寫的標(biāo)記語言，通過簡單的標(biāo)記語法，它可以使普通文本內(nèi)容具有一定的格式。說白了，就是它可以再轉(zhuǎn)換成HTML代碼，最后進(jìn)行文檔排版。




現(xiàn)在，已經(jīng)有很多平臺都支持了markdown的格式。
例如，Gitlab、Github、Gee：



又如各大信息類平臺：
圖靈社區(qū)：



掘金：




另一方面，支持markdown的語言、系統(tǒng)、IDE開發(fā)環(huán)境、軟件、平臺和js編輯器也很豐富。




markdown格式也是很容易理解的，例如大標(biāo)題、小標(biāo)題的格式：

# 一級標(biāo)題## 二級標(biāo)題### 三級標(biāo)題#### 四級標(biāo)題##### 五級標(biāo)題###### 六級標(biāo)題
其他格式可自行查閱各大資料說明。

使用本地文本編輯器編寫markdown文檔

不管你用的是windows系統(tǒng)，還是Linux，還是Mac手提，都有很多文本編輯器是支持markdown的編寫以及預(yù)覽。

markdown文檔的后綴名是md，例如常見的頂頂有名的README.md。

例如我在Macbook上使用SubEthaEdit：

編輯界面如下（后面可以看到相應(yīng)的訪問效果）：

在編輯時，編輯器會自動幫你進(jìn)行markdown格式的高亮，非常友好。

使用docsify搭建你的文檔網(wǎng)站

了解完偉大的markdown格式后，接下來你就可以使用docsify把寫好的markdown文檔進(jìn)行在線展示了。


docsify是一個基于javascript運行的開源項目，不需要任何PHP、java、數(shù)據(jù)庫后端的依賴，就可以直接展示你的在線文檔。

docsfiy官網(wǎng)：https://docsify.js.org/#/?id=docsify-4113
顯示效果：



來一個更完整的文檔截圖：


不用擔(dān)心英文的問題，文檔上的內(nèi)容都是可以自己設(shè)置和編寫的。

docsify支持文檔搜索、左側(cè)菜單、頂端菜單、封面等。

例如，PhalApi開源框架使用docsify搭建的效果：

項目封面：

文檔正文：

搜索效果（留意左邊）：

同時完美支持移動端訪問文檔：

使用果創(chuàng)云文檔編寫你的技術(shù)文檔

最后，如何你不想搭建自己的文檔網(wǎng)站，也可以直接使用果創(chuàng)云的在線文檔，來編寫自己的技術(shù)文檔，分享你需要分享的項目成員查看。

果創(chuàng)云在線文檔就是基于docsify搭建和markdown格式來編寫的。

首先，進(jìn)入果創(chuàng)云開放平臺：http://open.yesapi.cn

然后，進(jìn)入【文檔】：http://open.yesapi.cn/wiki/home



進(jìn)入后，便可以創(chuàng)建你的項目文檔，支持創(chuàng)建多個項目文檔。


接著，就可以在線編輯你的文檔，并且實時預(yù)覽。



編寫完成后，就可以查看你的文檔。


文檔展示效果：



為保護(hù)你的文檔，你可以設(shè)置項目文檔的查看密碼：


這時候，需要填寫密碼才能查看你的文檔：



立即開始編寫我的文檔！
進(jìn)入果創(chuàng)云，立即開始編寫你的技術(shù)文檔吧~！