如何寫好產品幫助文檔？

大多數程序員都不喜歡寫文檔，有寫文檔時間，還不如重構一遍代碼。早前我也這麼認爲，究其緣由，一則本身不喜歡也不擅長寫文檔，代碼是給機器讀的，只要語法和邏輯沒問題，計算機就會聽命執行，而文檔是寫給人看的，除了語法和邏輯，好文檔還要照顧讀者的心理；二則傳統軟件的客戶對文檔無感，它僅僅做爲合同約定的交付物存在，客戶壓根就不會讀這些文檔，他們更依賴咱們提供的現場培訓和技術支持，讓客戶看文檔自學太不符合甲方的身份了。

但現現在大部分軟件產品都經過互聯網向用戶提供服務了，在線文檔纔是最高效的客戶服務通道，咱們熟知的那些開源軟件都配有高質量的在線文檔。好文檔是優秀產品的標配，它不只能夠幫你帶來更多的用戶，並且還能夠幫你服務更多的用戶。做爲互聯網程序員的你，要是不懂如何寫一份好的技術文檔，都很差意思跟人打招呼，更別想作出好的產品。

• 好文檔的評判標準是什麼

無從下手，不知道從什麼角度寫，寫些什麼，這是咱們常常遭遇的狀況，那爲何會發生這種狀況呢？一般是沒有找到寫做的意義，若是是爲了交差而寫，腦殼很容易卡殼，思路沒法拓展。在敲鍵盤以前，咱們先要想清楚這份文檔是寫給誰看的，經過這份文檔能夠幫讀者解決什麼問題。寫做是咱們輸出影響力的一種能力，其最終目的是爲了改變讀者的信息、行爲或信仰等，不然就是言之無物的垃圾。等明確了目標讀者和意義以後，咱們的思路也就打開了。

在想清楚這個問題以前，咱們最好不要動手寫文檔，但真實狀況是在不知道該寫什麼時，許多人就拿大量的實現細節來濫竽充數，包括代碼片斷和配置說明等，主要目的就是增長文檔的篇幅，他的出發點不是用戶需不須要，而是我擅長和熟悉什麼，用戶很容易被你的細節內容搞的不知所云。這就比如某我的的武藝很高，總愛在人前炫技，而不是在幫助他人解決問題的過程當中顯露本身的本領，一般這種人很遭人反感的。

編寫技術文檔的過程當中會遇到哪些常見問題呢？一般咱們習慣一上來就很是詳盡地介紹這款產品有哪些特性，具體怎麼安裝、配置和使用等等，其實大部分潛在用戶都是初次接觸此類產品，他對咱們的產品尚未完整的認知，壓根不知道這款產品到底能幫他解決什麼問題，對他而言有什麼價值，一上來就深刻細節就很容易把潛在用戶搞蒙。

記得當年研究生畢業準備答辯幻燈片，導師給咱們傳授了一些經驗：「答辯就是將本身的研究結果展現給評委，改變評委對這個研究課題上的認知，以及對本身的印象，從而得到較高的評分。幻燈片最好從Why開始，告訴評委這個研究課題的背景和意義，有了這個上下文作鋪墊，評委纔可能對你的研究感興趣，纔會跟隨你瞭解後面的 What 和 How。」

非功能特性是依附在功能特性上的，一款對用戶毫無價值的產品，即便其非功能特性很優秀，那也引不起用戶的興趣。技術文檔的開篇必需要經過介紹產品或方案的價值來跟用戶創建鏈接，讓他知道這款產品或方案跟他的工做是息息相關的，它能夠幫助他優化工做。接下來纔是讓用戶瞭解這款產品或方案是什麼，以及怎麼使用。這其實跟軟件研發的流程相似，從用戶需求開始，先分析梳理用戶的痛點，再到產品需求，設計一款產品來解決用戶的痛點，最後纔是開發實現。

• 文檔目錄設計與用戶思惟

 當咱們明確了文檔的目標讀者，也明確了能夠爲讀者解決哪些問題，寫做自己就有了指向和價值，這樣咱們就能夠調動身心和大腦，讓本身文思泉涌，這就是用戶思惟。在此基礎上，咱們就能夠開始考慮文檔應該包含哪些內容，目錄章節該怎樣安排設計才更符合用戶的學習規律。文檔就是咱們對外輸出的一個產品，作產品就要學會換位思考，站在用戶的視角考慮他們須要什麼樣的產品或方案，用戶在技術選型時也是先確認產品或方案對其是否有價值，等他承認了這個價值以後纔會進一步瞭解產品或方案的功能特性和使用方法。

今年上半年咱們團隊研發了一套微服務開發運維平臺，下半年咱們要把它推廣給集團各個專業公司的研發團隊，這時候咱們就在思考目標用戶當中哪些角色能夠決定是否採用這款產品？一般是應用架構師，但他首先要了解這款產品的總體定位和做用，相較於其餘同類產品有什麼優點，這個階段他不太關心產品的實現和操做等細節。另外，掌控感，或者說安全感，每一個人都但願擁有的，那咱們要幫用戶創建這種感受。在幫用戶解決具體問題以前，咱們要先搞定用戶的情緒問題，讓他在閱讀文檔時體驗更佳。

如何幫用戶得到掌控感或安全感呢？全景視圖，讓用戶擁有上帝視角，從總體上把握產品或方案的狀況，這個視圖不會包含太多細節。就像要穿越一片熱帶雨林到達某個地方，若是一頭就扎進森林裏，那咱們很容易就迷路了，最好是先爬上某處高地或樹冠，從那裏觀察整片森林的狀況，包括河流走向和地標特徵等，掌握了這些信息以後咱們就會更有安全感，更有把握走出這片森林。全景視圖就像一個裝載信息的框架，咱們要先幫用戶創建這個框架，後續再給用戶介紹詳細信息，這時候用戶就能夠把它們收納進這個框架的不一樣位置，這樣他就不輕易迷路了。所以，文檔第一部分是產品概述，包括背景說明、功能定位和優點比較等等。

在對這款產品有了總體瞭解以後，那應用架構師這個角色接下來就要搭建一套演示環境了，以便對產品有更加感性的認知。這個階段他不須要特別全面或深刻地瞭解各類細節，只須要知道如何以最簡單、最快速的方式把它配置運行起來，他能夠藉助這套環境給團隊內的開發測試人員介紹這款產品。所以，文檔第二部分是快速入門，主要是協助應用架構師把對概念理論的理解變成一套真實可見的演示環境。

經過上述兩部份內容，咱們讓用戶知道這款產品能夠幫他解決什麼問題，以及它是怎樣運行的。接下來用戶當中的開發、測試工程師等角色纔會介入進來，他們須要深刻了解產品的功能特性和使用方法，以便指導具體的編碼實現。所以，文檔的第三部分纔是介紹產品特性的開發指南。不一樣角色的用戶對文檔有不一樣的需求，文檔的章節目錄設計要依照上述順序來知足各種用戶的需求。第四部分，除了知道怎樣使用這款產品以外，用戶還會關心在平常使用過程當中怎樣運營維護它，有沒有一些配套工具或管理控制檯，藉助它監控微服務的運行狀況，以及對微服務進行管控治理等等。第五部分，使用過程當中遇到問題怎麼辦，尤爲某些出現頻率很是高的問題，這部分就要對這些常見問題作梳理，遭遇問題時方便用戶查閱。

1. 產品簡介
2. 快速入門
    1. 快速搭建環境
    2. 快速開發應用
3. 開發指南
    1. 基礎開發指南
    2. 進階開發指南
    3. 擴展開發指南
4. 操做指南
    1. 服務治理指南
    2. 網關配置指南
5. 常見問題
6. 經典案例
7. 歷史版本
8. 下載說明

• 故事思惟讓文檔再也不枯燥

文檔的章節目錄設計要圍繞用戶需求：首先，咱們要分析用戶的類型，明確哪些類型的用戶會先接觸到這款產品；再者，說服了這批用戶以後會帶來哪些新類型的用戶，這就是產品推廣過程當中接觸用戶的天然過程。在線文檔的主要做用就是幫助咱們得到新的用戶，但咱們必需要記住，推廣產品是咱們一廂情願的想法，是站在咱們的立場角度考慮問題，它是第二位的。寫文檔必需要先站在用戶的立場角度，幫他們解決具體的問題，在解決問題的過程當中順便推銷了產品，這纔是用戶思惟的價值所在。

與用戶思惟同等重要的另外一個思惟模式叫作故事思惟，這是人類大腦在漫長的進化過程當中造成的生理特質所決定的，咱們對故事類信息的接收會更加高效一些。若是你乾巴巴地羅列產品功能特性，就像傳統的產品使用說明書同樣，那用戶在閱讀這份文檔時是無感的，他會以爲枯燥無味、困難重重，沒法將產品跟他遇到的問題聯繫起來。此時，咱們就須要採用故事思惟來組織包裝這些素材，結合用戶的使用場景講故事。

故事思惟的落地關鍵在於設計一個故事劇本，就像拍攝一部電影或者創做一本小說，你須要設計好每一幕的故事梗概，第一步幹什麼，第二步幹什麼，第三步幹什麼，...... 把每一步會出現哪些角色元素、這一步他們須要完成什麼事情想清楚。那怎樣設計這個故事劇本呢？竅門就是思考用戶是怎樣使用咱們這款產品的，仍是以微服務開發運維平臺爲例，咱們在「快速入門 -> 快速搭建環境」章節就設計了這樣一個劇本：

1. 介紹微服務應用的標準架構
2. 搭建微服務必備組件：註冊中心
3. 構建一個扮演Provider的微服務
4. 構建一個扮演Consumer的微服務
5. 搭建微服務必備組件：API網關
6. 搭建微服務必備組件：配置中心
7. 搭建微服務必備組件：治理中心
8. 對照標準架構介紹演示環境

這個劇本是根據用戶真實使用過程設計的，經過收集整理這些典型場景提煉出故事劇本，經過劇本組織各類素材。在閱讀這份文檔時，用戶就會天然而然地代入到他真實的工做場景中，由於在用戶腦海裏本來就存在一些上下文，故事就是幫用戶把上下文調度出來，這會有助於更好地理解文檔，對文檔能夠帶給他的價值有更清晰的認知。經過自助閱讀文檔解決了真實的問題，作到不求人會讓他更有成就感。

• 故事線模擬用戶學習過程

等故事的基本框架肯定以後，咱們就能夠依次填充故事的各個部分，第一步該搭建哪一個部件，第二步又該搭建哪一個部件等等，一步一步層級遞進，後續步驟依賴於前序步驟，從而構成一個嚮導式按部就班過程，引導用戶由淺入深、由易到難，這符合天然的學習過程，這樣更容易讓用戶接受。

編寫技術文檔時有一種常見問題就是章節之間沒有關聯，彼此之間沒有轉承銜接，各部份內容比較零散，就像把不一樣主題的文章作成了雜文集。用戶在閱讀此類文檔時思惟很跳躍，剛看完一個內容，再看另一個，這二者沒有必然的聯繫。這其實也是沒有站在用戶角度思考問題，用戶跟咱們不同，他對產品或方案不像咱們這樣熟悉，缺乏咱們所掌握的隱性信息，章節內容上的跳躍加劇了用戶閱讀文檔的難度。最好就是找到一條線索將每一個章節的內容銜接起來，就像章回體小說同樣，看完這章想下章。借鑑Oracle JDK的示例工程寵物商店（Java Pet Store），咱們也設計了一個簡單但完整的用戶信息管理服務來貫穿整個故事。

• 進階式設計跨越學習曲線

在文檔內容編排方面，咱們不要一次性讓用戶學習太多新東西，嚮導裏每一個步驟的內容分佈，必需要符合進階式的學習模型，一會兒給用戶展現太多信息，只會把用戶搞懵圈，讓他產生畏難的情緒，對學習喪失興趣。每一個小節的內容不能填充的太多，儘可能控制在十五分鐘到半個小時之內，用戶只要稍稍努力就能夠完成挑戰，這樣用戶就會感覺到學習的樂趣，小步快跑，每一次小小的進步均可以激勵自我，這樣他就有信心自助式地完成整個系統的學習了。這樣的學習方式是符合人性的，符合學習心理學的。

近段時間參與外部客戶項目寫標書，剛開始你們都無從下手，打不開思路，想着從網絡上摘抄一些內容粘貼進去，但這樣寫做味同嚼蠟，寫的不開心，讀的也沒感受。後來就想到咱們必需要揣摩讀者，想象對面就坐着讀者。標書的讀者是跟咱們同樣在專業領域有着豐富經驗的評委，咱們沒有必要向他講解任何概念性的內容，在標書中咱們只須要圍繞客戶的問題提供解決方案，簡明扼要，點到爲止，這樣便是對評委的尊重，也是體現咱們的專業性，咱們不是出售文字，而是出售專業經驗，就是有個流傳甚廣的故事裏說的，一個專家被請去給工廠診斷故障緣由，他在工廠裏轉了一圈只用粉筆花了一個叉叉，就掙了十萬美金。

不一樣的讀者要採用不一樣的溝通方式，除了要清楚讀者的角色和能力等級，還要知道本身在此次對話中扮演的角色，俯視時要就低不就高，仰視時也要就低不就高，平視時作到點到爲止，即讀者的能力水平跟本身類似，那就要作到簡明扼要、重點突出。從讀者角度看，照顧對方的心理，讓他感到舒服就對了。

• 不一樣視圖服務不一樣的用戶

那你可能會說，除了新用戶還有許多老用戶須要看在線文檔，上述這種設計是否符合他們的使用習慣了呢？針對不一樣類型的用戶，咱們必需要提供不一樣的視圖，或者說不一樣的入口，例如按照產品的功能特性創建一個索引視圖，相似 Hao123 同樣的導航頁面，或者提供一個搜索框，深度用戶對咱們的產品已經很是熟悉了，他們能夠經過這些入口快速找到他們想要的內容，從而更加高效地使用這份文檔。一樣的內容經過不一樣的組織方式呈現給不一樣的用戶，這就是視圖法帶給咱們的價值，橫當作嶺側成峯，遠近高低各不一樣。

• 經常使用開源或免費文檔工具

文末再推薦幾款我平常寫做用的軟件工具：

1. 閃念膠囊：支持語音錄製和識別，好處是能夠很是便捷地記錄本身的想法，尤爲是當你靈光一閃的時候，鍵盤和紙筆都沒有語言表述來的快，本文的主體內容都是藉助它完成的。
2. 印象筆記：支持手機和電腦之間同步，在手機上寫到一半的文檔能夠在電腦上繼續寫，反之亦然，作到無縫銜接，不會由於切換工具就影響了寫做的連續性。
3. 錘子便籤：一樣是錘子科技出品，它是我在手機上碼字最喜歡用的工具，純粹到讓你有寫做的意願。
4. MWeb Lite：MacBook 上編輯 Markdown 文本工具，免費易用，手機上我就用網易的有道筆記。

技術人習慣從本身角度看問題，產品人習慣從用戶角度想問題，技術人也要掌握產品思惟，用戶思惟和故事思惟是很是有效的兩套方法論，市面上有不少經典書籍介紹它們，感興趣的朋友能夠找來看一看。今天先分享到這裏，若是你以爲有價值，麻煩動動手指 轉發 給其餘須要的小夥伴。另外，老兵哥我後續還會分享職業規劃、應聘面試、技能提高、影響力打造等經驗，歡迎 關注 本博客或歪信公衆號「 IT老兵哥 」！