如何寫出優(yōu)秀的技術(shù)文檔？

大家好，我是小棗君。

鮮棗課堂自從2017年5月開始正式創(chuàng)立，迄今已有3年多的時間。這一期間，我們的內(nèi)容一直都堅持以技術(shù)類科普文章為主，輸出了大約400多篇原創(chuàng)。其中絕大部分，都是我寫的。

我的想法比較簡單，就是希望能夠輸出通俗易懂的技術(shù)科普文章，讓技術(shù)不再枯燥，幫助更多人（尤其是即將進入行業(yè)的年輕人）了解通信，了解5G、物聯(lián)網(wǎng)、云計算和大數(shù)據(jù)這樣的ICT領(lǐng)域前沿科技知識。

非常慶幸的是，鮮棗課堂的內(nèi)容受到了大家的歡迎，得到了寶貴的認可，也積累了越來越大的影響力。我們現(xiàn)在已經(jīng)逐漸成為行業(yè)里排名前列的技術(shù)類內(nèi)容原創(chuàng)自媒體。

其實，我之所以會選擇技術(shù)文章寫作這條路，和我的個人經(jīng)歷是分不開的。

我曾經(jīng)在某設(shè)備商做了四年的技術(shù)支持（其中三年海外），積累了豐富的通信產(chǎn)品技術(shù)知識和實踐經(jīng)驗。然后，又做了三年的文檔經(jīng)理，積累了大量的文檔寫作、文檔體系建設(shè)、文檔質(zhì)量管理方面的經(jīng)驗。最后，又做了四五年的培訓(xùn)經(jīng)理，學(xué)習(xí)如何進行高效的內(nèi)容表達、如何針對內(nèi)外部客戶進行知識傳遞。

多元化的職場經(jīng)歷，為我創(chuàng)辦鮮棗課堂貢獻了知識背景和能力基礎(chǔ)。

尤其是技術(shù)文檔寫作這一塊，我從剛?cè)肼毦宛B(yǎng)成了經(jīng)驗隨手總結(jié)、技術(shù)定期積累的日常寫作習(xí)慣，并保持至今，可以說是受益匪淺。

文檔，不管是對于員工個人，還是對于企業(yè)，都有非常重要的意義。對于技術(shù)類公司來說，技術(shù)文檔的重要性更是不言而喻。它的價值，完全可以等同于產(chǎn)品本身。或者說，技術(shù)文檔就是產(chǎn)品的一個重要組成部分。

很多人認為文檔是產(chǎn)品的附屬品，是例行公事的印刷品，這顯然是不對的。

文檔的根本性質(zhì)，是貫穿產(chǎn)品生命周期的沉淀積累輸出物，是信息傳遞的重要工具和載體。不同階段的文檔，有不同的作用。不同的崗位，有不同的文檔體系。

在產(chǎn)品設(shè)計和研發(fā)階段，有產(chǎn)品設(shè)計指導(dǎo)書、產(chǎn)品功能需求說明書等。在產(chǎn)品工程交付階段，有版本發(fā)布說明、技術(shù)指導(dǎo)書、升級/割接/擴容指導(dǎo)書等。

產(chǎn)品文檔體系的范例

文檔還分為內(nèi)部文檔和外部文檔。內(nèi)部文檔服務(wù)于內(nèi)部用戶，外部文檔服務(wù)于客戶、合作方等外部用戶。內(nèi)外部文檔密級不同，內(nèi)容會有所刪減，表述方式和側(cè)重點也會有所不同。

文檔用于指導(dǎo)實際工作。文檔質(zhì)量的好壞，會影響信息傳遞的準確性和效率，進而影響工作的完成、項目的交付。

例如，產(chǎn)品開通文檔太爛，客戶看不懂，合作方員工看不懂，甚至自己的工程師也看不懂，就無法依照文檔成功完成設(shè)備開通或升級割接。文檔如果出現(xiàn)錯誤，甚至可能造成嚴重的事故。

現(xiàn)在市場競爭越來越激烈。有時候，雖然產(chǎn)品本身做得很好，價格也很有優(yōu)勢，但是文檔太爛，一樣會被客戶鄙視，進而拉低了產(chǎn)品的整體競爭力。有損公司品牌形象。

那么，決定產(chǎn)品文檔質(zhì)量的基本要素是什么呢？

有人說，是作者的寫作水平。也有人說，是是否有充足的時間。

其實都不對，基本要素只有一個，那就是錢。

文檔寫作是一個需要投入大量資源的工作。

首先，需要建立一個完善的文檔管理體系，包括文檔架構(gòu)體系，文檔職責(zé)歸屬，文檔立項、開發(fā)、評審、發(fā)布、歸檔流程以及對應(yīng)平臺等。

其次，需要安排大量的專任或兼任崗位跟進相關(guān)流程管理，占用工時。

再有，文檔和產(chǎn)品開發(fā)一樣，是一個滾動性流程，需要不斷更新迭代。所以，資源投入也是持續(xù)性的。

早期的時候，國內(nèi)很多企業(yè)利用人力成本優(yōu)勢，發(fā)起人海戰(zhàn)術(shù)，將資源集中投入到產(chǎn)品研發(fā)上，靠價格優(yōu)勢和版本速度（需求響應(yīng)速度）搶占市場。

開發(fā)工程師忙著寫代碼，做版本，哪有時間去寫文檔？基本上都是拿產(chǎn)品設(shè)計指導(dǎo)書改一改，截截圖，就扔給了售后，甚至扔給了客戶。

內(nèi)部用戶（售后）罵娘，領(lǐng)導(dǎo)其實心里有數(shù)，畢竟資源有限，只能犧牲文檔保版本，對內(nèi)部反饋進行彈壓。而外部客戶的意見，是無法進行彈壓的。

對于一些低端客戶來說，比較關(guān)注的是價格。極端的成本優(yōu)勢，可以讓客戶忽視文檔。但是，對于高端用戶來說，他們對文檔的要求和對產(chǎn)品的要求是一致的。沒有優(yōu)秀齊套的文檔，一樣不給中標。

于是，倒逼設(shè)備商投入資源補齊短板，組織人力進行文檔專項開發(fā)。結(jié)果發(fā)現(xiàn)，其實并不是寫不出好文檔，而是之前沒有舍得投入資源。

然而，一旦項目應(yīng)付過去，資源又會撤走，好不容易建立起來的文檔質(zhì)量，又再次垮塌，如此惡性循環(huán)。

所以說，對于企業(yè)，想要把文檔滿意度搞好，樹立有利于產(chǎn)品品牌的文檔品牌形象，關(guān)鍵在于領(lǐng)導(dǎo)愿不愿意投錢。有錢就有人有資源，這是搞好文檔的基本前提。

隨著市場的規(guī)范和成熟，加上競爭日趨激烈，文檔的重要性不斷提升，越來越多的企業(yè)負責(zé)人開始意識到這個問題，不斷加大對文檔的資源投入。

戰(zhàn)略層面的重視是基礎(chǔ)，戰(zhàn)術(shù)層面的執(zhí)行是關(guān)鍵。

前面說的文檔管理體系，是有一整套方法論的。大到文檔體系的架構(gòu)（到底需要多少篇文檔，分別由誰來負責(zé)，寫給誰看），小到文檔內(nèi)容的編寫，都有相應(yīng)的理論和技巧。這些不是靠人海戰(zhàn)術(shù)就可以完美完成的。

限于篇幅，我就不詳細介紹文檔管理體系了。我重點說說單篇文檔的寫作技巧。

想要寫好一篇文檔，首先第一個問題，就是你要搞清楚這篇文檔的定位——它是一篇什么性質(zhì)的文檔？寫作目的是什么？它的使用者是誰？

文檔的定位，直接決定了整篇文檔的基調(diào)。

例如我經(jīng)常寫的零基礎(chǔ)入門，定位就是對相關(guān)內(nèi)容背景知識毫無了解的讀者。然而，又不是小學(xué)生那種層次，而是至少已經(jīng)完成了基礎(chǔ)教育，處于大一及以上學(xué)歷水平的讀者，有基本的物理學(xué)和數(shù)學(xué)常識，也有對自然現(xiàn)場的基本認知，還有正常人的邏輯思維能力。

如果你寫技術(shù)文檔，首先要搞明白，文檔使用者是內(nèi)部客戶還是外部客戶，是有經(jīng)驗的客戶，還是零基礎(chǔ)的客戶，是已經(jīng)閱讀過前置文檔的客戶，還是第一次看這套文檔的客戶。

明確了對象之后，要切記，在寫作整篇文檔的過程中，你都要隨時切換自身角色。一定要站在讀者的角度，琢磨文檔內(nèi)容是不是能看得懂。

如果沒有把握，那么，就找個和目標讀者處于同等水平的體驗用戶，讓他試讀，提供反饋意見。

大部分技術(shù)文檔的作者不是作家，甚至不是文科生，而是技術(shù)工程師。這類人在文字表達技巧上通常比較欠缺，但是有一個顯著優(yōu)勢，那就是邏輯思維能力強。對于寫作來說，這一點非常重要。尤其是技術(shù)文檔的寫作，必須有很強的邏輯思維能力。

文檔的總體結(jié)構(gòu)，必須要有邏輯連貫的章節(jié)順序。文檔的語句，也必須有邏輯嚴謹?shù)谋硎龇绞健＿^于跳躍的思維，不適合應(yīng)用于技術(shù)類文檔。文科生過于感性的文字，也不適合技術(shù)類文檔。

技術(shù)工程師最常犯的毛病，就是自以為是：“這么簡單，你怎么都不懂？”“這是基礎(chǔ)啊，是個人都懂！”然后就偷工減料，言簡意賅，跳過了大量的細節(jié)，忽視了可能出現(xiàn)的不同情況，讓文檔使用者不知所措。甚至有的作者，喜歡玩“玄學(xué)”，覺得越寫得高深，就越顯得自己很懂，簡直可笑。

規(guī)范的技術(shù)文檔，通常會遵循SOP的原則。所謂SOP，就是 Standard Operating Procedure，標準作業(yè)程序。

下面這段內(nèi)容，是一個SOP文檔寫作的范例：

大家會看到，前置信息非常充分，該介紹的背景，都會介紹到位。

具體的操作步驟，雖然簡短，但內(nèi)容十分清晰，分為幾個步驟，每一個步驟敲什么命令、有什么目的，都會告訴你。

在最后，還會有驗證結(jié)果環(huán)節(jié)（本例的驗證結(jié)果部分相對簡略，實際上還應(yīng)該包括通過命令，查看結(jié)果，以此進行明確驗證）。

上面這種SOP的文檔寫作方式，和我們從小接受過的傳統(tǒng)寫作是完全不同的，

以前我們常說，中式菜譜喜歡用“鹽少許、醬油少許、大火煎炸片刻”這種定量非常模糊的表達方式，其實確實和我們的寫作習(xí)慣有一定關(guān)系。對于技術(shù)文檔來說，我們這方面的偏重性培養(yǎng)和訓(xùn)練確實做得不夠。真正的寫作，不是刻意追求辭藻的華麗，而是意思和情境的準確表達。

要想寫好技術(shù)文檔，還有一個重要技巧，那就是多用圖表。

所謂“字不如表、表不如圖”。技術(shù)是很抽象的東西，也是理解起來很有難度的東西。想要靠純文字進行內(nèi)容轉(zhuǎn)述，是很困難的。所以，應(yīng)該更多地借助表格和圖片，甚至gif動圖，幫助讀者理解。

說白了，這個就是考驗作者的責(zé)任心。如果寫作者不能站在讀者的角度，不能以讀者滿意度為出發(fā)點，那么，就不會愿意多此一舉去畫圖。畫圖是很復(fù)雜的工作，有時候我寫文章，一幅圖都要畫一天，很不容易。

技術(shù)文檔的寫作，不僅對企業(yè)來說非常重要，對于個人來說，也是受益匪淺的。

養(yǎng)成并堅持寫作的習(xí)慣，有利于培養(yǎng)邏輯思維能力，也有利于個人知識沉淀積累。個人可以開技術(shù)blog或公眾號，發(fā)表并分享自己的經(jīng)驗心得，會很有成就感，日積月累的話，甚至可能形成個人品牌和影響力，有利于自己的職業(yè)生涯發(fā)展。

雖然現(xiàn)在視頻化的趨勢明顯，但是我個人認為，文檔是無法被視頻取代的。目前的技術(shù)，視頻無法進行快速內(nèi)容檢索，無法進行快速更新和修改，無法進行快速傳遞，文件體積較大，這些都決定了文檔的不可替代性。

視頻的優(yōu)勢，更多在于內(nèi)容形象而生動的展示，可以讓用戶有更感性的認識，更深刻的記憶，適合培訓(xùn)，不適合工作查閱，不適合歸檔。

好啦，以上就是小棗君關(guān)于技術(shù)文檔寫作的分享，希望對大家有所幫助。順便打個小廣告，大家如果有自己覺得還不錯的技術(shù)文檔輸出，也歡迎投稿給鮮棗課堂，稿酬豐厚！

最后，感謝大家的耐心閱讀，我們下期再見啦！

—— The End ——