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

但現如今大部分軟體產品都通過網際網路向用戶提供服務了，線上文件才是最高效的客戶服務通道，我們熟知的那些開源軟體都配有高質量的線上文件。好文件是優秀產品的標配，它不僅可以幫你帶來更多的使用者，而且還可以幫你服務更多的使用者。作為網際網路程式設計師的你，要是不懂如何寫一份好的技術文件，都不好意思跟人打招呼，更別想做出好的產品。

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

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

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

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

記得當年研究生畢業準備答辯幻燈片，導師給我們傳授了一些經驗：“答辯就是將自己的研究結果展示給評委，改變評委對這個研究課題上的認知，以及對自己的印象，從而獲得較高的評分。幻燈片最好從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老兵哥