?2016-2026 Matools All rights reserved,
粵ICP備17059708號
大多數(shù)程序員都不喜歡寫文檔，有寫文檔時間，還不如重構(gòu)一遍代碼。早前我也這么認為，究其原因，一則自己不喜歡也不擅長寫文檔，代碼是給機器讀的，只要語法和邏輯沒問題，計算機就會聽命執(zhí)行，而文檔是寫給人看的，除了語法和邏輯，好文檔還要照顧讀者的心理；二則傳統(tǒng)軟件的客戶對文檔無感，它僅僅作為合同約定的交付物存在，客戶壓根就不會讀這些文檔，他們更依賴我們提供的現(xiàn)場培訓和技術(shù)支持，讓客戶看文檔自學太不符合甲方的身份了。
但現(xiàn)如今大部分軟件產(chǎn)品都通過互聯(lián)網(wǎng)向用戶提供服務(wù)了，在線文檔才是最高效的客戶服務(wù)通道，我們熟知的那些開源軟件都配有高質(zhì)量的在線文檔。好文檔是優(yōu)秀產(chǎn)品的標配，它不僅可以幫你帶來更多的用戶，而且還可以幫你服務(wù)更多的用戶。作為互聯(lián)網(wǎng)程序員的你，要是不懂如何寫一份好的技術(shù)文檔，都不好意思跟人打招呼，更別想做出好的產(chǎn)品。
* 好文檔的評判標準是什么
無從下手，不知道從什么角度寫，寫些什么，這是我們經(jīng)常遭遇的情況，那為什么會發(fā)生這種情況呢？通常是沒有找到寫作的意義，如果是為了交差而寫，腦袋很容易卡殼，思路無法拓展。在敲鍵盤之前，我們先要想清楚這份文檔是寫給誰看的，通過這份文檔可以幫讀者解決什么問題。寫作是我們輸出影響力的一種能力，其最終目的是為了改變讀者的信息、行為或信仰等，否則就是言之無物的垃圾。等明確了目標讀者和意義之后，我們的思路也就打開了。
在想清楚這個問題之前，我們最好不要動手寫文檔，但真實情況是在不知道該寫什么時，許多人就拿大量的實現(xiàn)細節(jié)來濫竽充數(shù)，包括代碼片段和配置說明等，主要目的就是增加文檔的篇幅，他的出發(fā)點不是用戶需不需要，而是我擅長和熟悉什么，用戶很容易被你的細節(jié)內(nèi)容搞的不知所云。這就好比某個人的武藝很高，總愛在人前炫技，而不是在幫助他人解決問題的過程中顯露自己的本領(lǐng)，通常這種人很遭人反感的。
編寫技術(shù)文檔的過程中會遇到哪些常見問題呢？通常我們習慣一上來就非常詳盡地介紹這款產(chǎn)品有哪些特性，具體怎么安裝、配置和使用等等，其實大部分潛在用戶都是初次接觸此類產(chǎn)品，他對我們的產(chǎn)品還沒有完整的認知，壓根不知道這款產(chǎn)品到底能幫他解決什么問題，對他而言有什么價值，一上來就深入細節(jié)就很容易把潛在用戶搞蒙。
記得當年研究生畢業(yè)準備答辯幻燈片，導師給我們傳授了一些經(jīng)驗：“答辯就是將自己的研究結(jié)果展示給評委，改變評委對這個研究課題上的認知，以及對自己的印象，從而獲得較高的評分。幻燈片最好從Why開始，告訴評委這個研究課題的背景和意義，有了這個上下文做鋪墊，評委才可能對你的研究感興趣，才會跟隨你了解后面的
What 和 How?！?br>
非功能特性是依附在功能特性上的，一款對用戶毫無價值的產(chǎn)品，即使其非功能特性很優(yōu)秀，那也引不起用戶的興趣。技術(shù)文檔的開篇必須要通過介紹產(chǎn)品或方案的價值來跟用戶建立連接，讓他知道這款產(chǎn)品或方案跟他的工作是息息相關(guān)的，它可以幫助他優(yōu)化工作。接下來才是讓用戶了解這款產(chǎn)品或方案是什么，以及怎么使用。這其實跟軟件研發(fā)的流程類似，從用戶需求開始，先分析梳理用戶的痛點，再到產(chǎn)品需求，設(shè)計一款產(chǎn)品來解決用戶的痛點，最后才是開發(fā)實現(xiàn)。
* 文檔目錄設(shè)計與用戶思維
?當我們明確了文檔的目標讀者，也明確了可以為讀者解決哪些問題，寫作本身就有了指向和價值，這樣我們就可以調(diào)動身心和大腦，讓自己文思泉涌，這就是用戶思維。在此基礎(chǔ)上，我們就可以開始考慮文檔應(yīng)該包含哪些內(nèi)容，目錄章節(jié)該怎樣安排設(shè)計才更符合用戶的學習規(guī)律。文檔就是我們對外輸出的一個產(chǎn)品，做產(chǎn)品就要學會換位思考，站在用戶的視角考慮他們需要什么樣的產(chǎn)品或方案，用戶在技術(shù)選型時也是先確認產(chǎn)品或方案對其是否有價值，等他認可了這個價值之后才會進一步了解產(chǎn)品或方案的功能特性和使用方法。
今年上半年我們團隊研發(fā)了一套微服務(wù)開發(fā)運維平臺，下半年我們要把它推廣給集團各個專業(yè)公司的研發(fā)團隊，這時候我們就在思考目標用戶當中哪些角色可以決定是否采用這款產(chǎn)品？通常是應(yīng)用架構(gòu)師，但他首先要了解這款產(chǎn)品的整體定位和作用，相較于其他同類產(chǎn)品有什么優(yōu)勢，這個階段他不太關(guān)心產(chǎn)品的實現(xiàn)和操作等細節(jié)。另外，掌控感，或者說安全感，每個人都希望擁有的，那我們要幫用戶建立這種感覺。在幫用戶解決具體問題之前，我們要先搞定用戶的情緒問題，讓他在閱讀文檔時體驗更佳。
如何幫用戶獲得掌控感或安全感呢？全景視圖，讓用戶擁有上帝視角，從整體上把握產(chǎn)品或方案的情況，這個視圖不會包含太多細節(jié)。就像要穿越一片熱帶雨林到達某個地方，如果一頭就扎進森林里，那我們很容易就迷路了，最好是先爬上某處高地或樹冠，從那里觀察整片森林的情況，包括河流走向和地標特征等，掌握了這些信息之后我們就會更有安全感，更有把握走出這片森林。全景視圖就像一個裝載信息的框架，我們要先幫用戶建立這個框架，后續(xù)再給用戶介紹詳細信息，這時候用戶就可以把它們收納進這個框架的不同位置，這樣他就不輕易迷路了。因此，文檔第一部分是產(chǎn)品概述，包括背景說明、功能定位和優(yōu)勢比較等等。
在對這款產(chǎn)品有了整體了解之后，那應(yīng)用架構(gòu)師這個角色接下來就要搭建一套演示環(huán)境了，以便對產(chǎn)品有更加感性的認知。這個階段他不需要特別全面或深入地了解各種細節(jié)，只需要知道如何以最簡單、最快速的方式把它配置運行起來，他可以借助這套環(huán)境給團隊內(nèi)的開發(fā)測試人員介紹這款產(chǎn)品。因此，文檔第二部分是快速入門，主要是協(xié)助應(yīng)用架構(gòu)師把對概念理論的理解變成一套真實可見的演示環(huán)境。
通過上述兩部分內(nèi)容，我們讓用戶知道這款產(chǎn)品可以幫他解決什么問題，以及它是怎樣運行的。接下來用戶當中的開發(fā)、測試工程師等角色才會介入進來，他們需要深入了解產(chǎn)品的功能特性和使用方法，以便指導具體的編碼實現(xiàn)。因此，文檔的第三部分才是介紹產(chǎn)品特性的開發(fā)指南。不同角色的用戶對文檔有不同的需求，文檔的章節(jié)目錄設(shè)計要依照上述順序來滿足各類用戶的需求。第四部分，除了知道怎樣使用這款產(chǎn)品之外，用戶還會關(guān)心在日常使用過程中怎樣運營維護它，有沒有一些配套工具或管理控制臺，借助它監(jiān)控微服務(wù)的運行情況，以及對微服務(wù)進行管控治理等等。第五部分，使用過程中遇到問題怎么辦，尤其某些出現(xiàn)頻率非常高的問題，這部分就要對這些常見問題做梳理，遭遇問題時方便用戶查閱。
1. 產(chǎn)品簡介 2. 快速入門 1. 快速搭建環(huán)境 2. 快速開發(fā)應(yīng)用 3. 開發(fā)指南 1. 基礎(chǔ)開發(fā)指南 2. 進階開發(fā)指南 3. 擴展開發(fā)指南 4.
操作指南 1. 服務(wù)治理指南 2. 網(wǎng)關(guān)配置指南 5. 常見問題 6. 經(jīng)典案例 7. 歷史版本 8. 下載說明
* 故事思維讓文檔不再枯燥
文檔的章節(jié)目錄設(shè)計要圍繞用戶需求：首先，我們要分析用戶的類型，明確哪些類型的用戶會先接觸到這款產(chǎn)品；再者，說服了這批用戶之后會帶來哪些新類型的用戶，這就是產(chǎn)品推廣過程中接觸用戶的自然過程。在線文檔的主要作用就是幫助我們獲得新的用戶，但我們必須要記住，推廣產(chǎn)品是我們一廂情愿的想法，是站在我們的立場角度考慮問題，它是第二位的。寫文檔必須要先站在用戶的立場角度，幫他們解決具體的問題，在解決問題的過程中順便推銷了產(chǎn)品，這才是用戶思維的價值所在。
與用戶思維同等重要的另一個思維模式叫做故事思維，這是人類大腦在漫長的進化過程中形成的生理特質(zhì)所決定的，我們對故事類信息的接收會更加高效一些。如果你干巴巴地羅列產(chǎn)品功能特性，就像傳統(tǒng)的產(chǎn)品使用說明書一樣，那用戶在閱讀這份文檔時是無感的，他會覺得枯燥無味、困難重重，無法將產(chǎn)品跟他遇到的問題聯(lián)系起來。此時，我們就需要采用故事思維來組織包裝這些素材，結(jié)合用戶的使用場景講故事。
故事思維的落地關(guān)鍵在于設(shè)計一個故事劇本，就像拍攝一部電影或者創(chuàng)作一本小說，你需要設(shè)計好每一幕的故事梗概，第一步干什么，第二步干什么，第三步干什么，......
把每一步會出現(xiàn)哪些角色元素、這一步他們需要完成什么事情想清楚。那怎樣設(shè)計這個故事劇本呢？竅門就是思考用戶是怎樣使用我們這款產(chǎn)品的，還是以微服務(wù)開發(fā)運維平臺為例，我們在“快速入門
-> 快速搭建環(huán)境”章節(jié)就設(shè)計了這樣一個劇本：
1. 介紹微服務(wù)應(yīng)用的標準架構(gòu) 2. 搭建微服務(wù)必備組件：注冊中心 3. 構(gòu)建一個扮演Provider的微服務(wù) 4. 構(gòu)建一個扮演Consumer的微服務(wù)
5. 搭建微服務(wù)必備組件：API網(wǎng)關(guān) 6. 搭建微服務(wù)必備組件：配置中心 7. 搭建微服務(wù)必備組件：治理中心 8. 對照標準架構(gòu)介紹演示環(huán)境
這個劇本是根據(jù)用戶真實使用過程設(shè)計的，通過收集整理這些典型場景提煉出故事劇本，通過劇本組織各種素材。在閱讀這份文檔時，用戶就會自然而然地代入到他真實的工作場景中，因為在用戶腦海里原本就存在一些上下文，故事就是幫用戶把上下文調(diào)度出來，這會有助于更好地理解文檔，對文檔可以帶給他的價值有更清晰的認知。通過自助閱讀文檔解決了真實的問題，做到不求人會讓他更有成就感。
* 故事線模擬用戶學習過程
等故事的基本框架確定之后，我們就可以依次填充故事的各個部分，第一步該搭建哪個部件，第二步又該搭建哪個部件等等，一步一步層級遞進，后續(xù)步驟依賴于前序步驟，從而構(gòu)成一個向?qū)窖驖u進過程，引導用戶由淺入深、由易到難，這符合自然的學習過程，這樣更容易讓用戶接受。
編寫技術(shù)文檔時有一種常見問題就是章節(jié)之間沒有關(guān)聯(lián)，彼此之間沒有轉(zhuǎn)承銜接，各部分內(nèi)容比較零散，就像把不同主題的文章做成了雜文集。用戶在閱讀此類文檔時思維很跳躍，剛看完一個內(nèi)容，再看另外一個，這兩者沒有必然的聯(lián)系。這其實也是沒有站在用戶角度思考問題，用戶跟我們不一樣，他對產(chǎn)品或方案不像我們這樣熟悉，缺少我們所掌握的隱性信息，章節(jié)內(nèi)容上的跳躍加重了用戶閱讀文檔的難度。最好就是找到一條線索將每個章節(jié)的內(nèi)容銜接起來，就像章回體小說一樣，看完這章想下章。借鑒Oracle
JDK的示例工程寵物商店（Java Pet Store），我們也設(shè)計了一個簡單但完整的用戶信息管理服務(wù)來貫穿整個故事。
* 進階式設(shè)計跨越學習曲線
在文檔內(nèi)容編排方面，我們不要一次性讓用戶學習太多新東西，向?qū)Ю锩總€步驟的內(nèi)容分布，必須要符合進階式的學習模型，一下子給用戶展示太多信息，只會把用戶搞懵圈，讓他產(chǎn)生畏難的情緒，對學習喪失興趣。每個小節(jié)的內(nèi)容不能填充的太多，盡量控制在十五分鐘到半個小時以內(nèi)，用戶只要稍稍努力就可以完成挑戰(zhàn)，這樣用戶就會感受到學習的樂趣，小步快跑，每一次小小的進步都可以激勵自我，這樣他就有信心自助式地完成整個系統(tǒng)的學習了。這樣的學習方式是符合人性的，符合學習心理學的。
近段時間參與外部客戶項目寫標書，剛開始大家都無從下手，打不開思路，想著從網(wǎng)絡(luò)上摘抄一些內(nèi)容粘貼進去，但這樣寫作味同嚼蠟，寫的不開心，讀的也沒感覺。后來就想到我們必須要揣摩讀者，想象對面就坐著讀者。標書的讀者是跟我們一樣在專業(yè)領(lǐng)域有著豐富經(jīng)驗的評委，我們沒有必要向他講解任何概念性的內(nèi)容，在標書中我們只需要圍繞客戶的問題提供解決方案，簡明扼要，點到為止，這樣即是對評委的尊重，也是體現(xiàn)我們的專業(yè)性，我們不是出售文字，而是出售專業(yè)經(jīng)驗，就是有個流傳甚廣的故事里說的，一個專家被請去給工廠診斷故障原因，他在工廠里轉(zhuǎn)了一圈只用粉筆花了一個叉叉，就掙了十萬美金。
不同的讀者要采用不同的溝通方式，除了要清楚讀者的角色和能力等級，還要知道自己在這次對話中扮演的角色，俯視時要就低不就高，仰視時也要就低不就高，平視時做到點到為止，即讀者的能力水平跟自己相似，那就要做到簡明扼要、重點突出。從讀者角度看，照顧對方的心理，讓他感到舒服就對了。
* 不同視圖服務(wù)不同的用戶
那你可能會說，除了新用戶還有許多老用戶需要看在線文檔，上述這種設(shè)計是否符合他們的使用習慣了呢？針對不同類型的用戶，我們必須要提供不同的視圖，或者說不同的入口，例如按照產(chǎn)品的功能特性建立一個索引視圖，類似
Hao123
一樣的導航頁面，或者提供一個搜索框，深度用戶對我們的產(chǎn)品已經(jīng)非常熟悉了，他們可以通過這些入口快速找到他們想要的內(nèi)容，從而更加高效地使用這份文檔。同樣的內(nèi)容通過不同的組織方式呈現(xiàn)給不同的用戶，這就是視圖法帶給我們的價值，橫看成嶺側(cè)成峰，遠近高低各不同。
* 常用開源或免費文檔工具
文末再推薦幾款我日常寫作用的軟件工具：
*
閃念膠囊：支持語音錄制和識別，好處是可以非常便捷地記錄自己的想法，尤其是當你靈光一閃的時候，鍵盤和紙筆都沒有語言表述來的快，本文的主體內(nèi)容都是借助它完成的。
* 印象筆記：支持手機和電腦之間同步，在手機上寫到一半的文檔可以在電腦上繼續(xù)寫，反之亦然，做到無縫銜接，不會因為切換工具就影響了寫作的連續(xù)性。
* 錘子便簽：同樣是錘子科技出品，它是我在手機上碼字最喜歡用的工具，純粹到讓你有寫作的意愿。
* MWeb Lite：MacBook 上編輯 Markdown 文本工具，免費易用，手機上我就用網(wǎng)易的有道筆記。
技術(shù)人習慣從自己角度看問題，產(chǎn)品人習慣從用戶角度想問題，技術(shù)人也要掌握產(chǎn)品思維，用戶思維和故事思維是非常有效的兩套方法論，市面上有很多經(jīng)典書籍介紹它們，感興趣的朋友可以找來看一看。今天先分享到這里，如果你覺得有價值，麻煩動動手指?
轉(zhuǎn)發(fā)?給其他需要的小伙伴。另外，老兵哥我后續(xù)還會分享職業(yè)規(guī)劃、應(yīng)聘面試、技能提升、影響力打造等經(jīng)驗，歡迎?關(guān)注?本博客或歪信公眾號「 IT老兵哥 」！
關(guān)注「?IT老兵哥?」，賦能程序人生！
熱門工具 換一換