大家好，我是小棗君。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

其實(shí)都不對(duì)，基本要素只有一個(gè)，那就是錢。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

如果沒有把握，那么，就找個(gè)和目標(biāo)讀者處于同等水平的體驗(yàn)用戶，讓他試讀，提供反饋意見。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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