大家好，我是小棗君。

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

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

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

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

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

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

尤其是技術文檔寫作這一塊，我從剛入職就養(yǎng)成了經驗隨手總結、技術定期積累的日常寫作習慣，并保持至今，可以說是受益匪淺。

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

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

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

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

產品文檔體系的范例

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

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

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

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

那么，決定產品文檔質量的基本要素是什么呢？

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

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

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

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

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

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

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

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

內部用戶（售后）罵娘，領導其實心里有數，畢竟資源有限，只能犧牲文檔保版本，對內部反饋進行彈壓。而外部客戶的意見，是無法進行彈壓的。

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

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

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

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

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

戰(zhàn)略層面的重視是基礎，戰(zhàn)術層面的執(zhí)行是關鍵。

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

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

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

文檔的定位，直接決定了整篇文檔的基調。

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

如果你寫技術文檔，首先要搞明白，文檔使用者是內部客戶還是外部客戶，是有經驗的客戶，還是零基礎的客戶，是已經閱讀過前置文檔的客戶，還是第一次看這套文檔的客戶。

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

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

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

文檔的總體結構，必須要有邏輯連貫的章節(jié)順序。文檔的語句，也必須有邏輯嚴謹的表述方式。過于跳躍的思維，不適合應用于技術類文檔。文科生過于感性的文字，也不適合技術類文檔。

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

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

下面這段內容，是一個SOP文檔寫作的范例：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

—— The End ——