|
|
文/蔡學鏞
技術文檔很多，每種文檔都有各自的目的。其中和架構師關系最密切的、甚至架構師應該親自寫的文檔是技術白皮書與技術路線圖，這兩份文檔是本次文章的重點。
技術白皮書
White Paper衍生自White Book（白皮書），一般也稱為白皮書，但是內容更濃縮、更精華。White Paper通常合起來寫為Whitepaper。
技術白皮書（Technical White Paper）是官方正式的報告指南，風格介于技術論文和商業雜志文章之間，用來描述大問題和技術解決方案。技術白皮書是常用的技術營銷的手段之一，它的目的是幫助讀者了解技術、做出決策。技術白皮書通常是以PDF文件格式存在，10頁左右的篇幅最恰當。
技術發明者（或擁有者）才能發表技術白皮書。例如，支付寶可以發表“總督系統”技術白皮書（我正在研發的一套CEP系統），但不可以發表Spring框架技術白皮書。支付寶計劃走向開放，未來可能會提供開放API，那時候就可以對外推出技術白皮書。
技術白皮書是“技術營銷”的文件，適合CTO、技術總監、技術專家之類的高層決策人士閱讀，讓他們通過“大局觀”的方式了解整個技術概況。技術白皮書的重點在于讓讀者深刻理解采用此技術將為他們帶來多大的利益。
編寫技術白皮書要把握以下重點：
- 技術白皮書代表官方，所以敘述風格必須具有權威性；
- 良好的技術白皮書通常會附上許多方塊圖，將技術內部的結構表達清楚，并說明和外部的關系；
- 如果無法使用示意圖時，盡量使用Bullet Point；
- 技術白皮書一定要把握重點，不可以長篇大論；
- 技術白皮書一定要有高技術含量，雞毛蒜皮的瑣碎細節一概不提；
- 以讀者的利益為敘述核心，而非以技術本身的先進或自身的利益為敘述核心。
上面的第6點是大部分技術白皮書的毛病所在，需要特別解釋。技術白皮書不應該淪為自言自語、自吹自捧，而是應該從“顧客第一”的角度分析讀者有什么問題，需要什么樣的技術，而我們的技術可能是一項不錯的解決方案，因為我們是如何如何做到的。
我建議的技術白皮書編寫框架如下：
- 封面：技術名稱、縮寫、版本；公司名稱、Logo；文檔日期。
- 不需要目錄，因為文檔不長，沒有必要提供目錄。
- 內容：依據上面述的六個重點編寫，格式自由安排。下面是建議內容：
- 摘要（約中文三百字的摘要）
- 簡介（What、Why、How等）
- 技術說明（架構等）
- Summary（總結）
- 文檔的法律聲明
技術路線圖
討論完技術白皮書，接下來看技術路線圖（Technology Roadmap）。
想要到達某個目標，可能不是一蹴而就的事，需要有路線規劃，讓大家一目了然地知道近期、中期、遠期的目標，這就是Roadmap（路線圖）。Roadmap也可以寫成Road Map。
Roadmap 應用相當廣泛：兩岸想統一，需要Roadmap；支付寶想要創造100倍的業績，需要Business Roadmap。如果過程涉及技術，那么這就是 Technology Roadmap。只有新產品、新興技術、相當復雜的產品可以有Technology Roadmap。如果僅是對產品做小改進，根本不需要Technology Roadmap。
技術路線圖有三個主要用途：
- 是一種規劃，幫助決定出一組需求，以及滿足此需求的技術；
- 是一種機制，可以幫助預測技術開發與走向；
- 是一種框架，可以用來幫助計劃與協調技術的開發。
隨著軟件產業越來越成熟，產品經理（Product Manager）也變成必備的職位。產品經理要負責整個開發過程的管理，在此過程中，制定產品路線可以幫助軟件產品經理規劃與分配資源。
制定技術路線圖分三個階段：
- 第一階段：初步行動；
- 第二階段：技術路線圖開發；
- 第三階段：后續行動。
可以看出第一階段是準備，第二階段是重點，第三階段是后續跟蹤修改。
在第一階段（初步行動），關鍵決策者發現他們有一個問題需要解決，而需要一份技術路線圖來幫助他們解決此問題，他們要這樣做：
- 1.1 滿足根本條件；
- 1.2 賦予領導權威或地位；
- 1.3 定義技術路線范圍和邊界。
在步驟1.1中，條件包含技術路線圖所需、來自組織不同部門（營銷、開發、戰略等部門）的輸入，這些部門有著不同的計劃區間（Planning Horizon）和不同的看事情角度。如果條件不滿足，則要采取行動來滿足條件。條件都滿足了，才能繼續下一個步驟。
步驟1.2的意思是：技術路線圖的建立牽涉到時間和各種資源，必須要有堅定的領導權威。領導權威必須來自參與者之一，由參與者之一賦予領導權威或地位。讓組織驅動此過程，并使用此路線圖來進行資源分配的決策。
在步驟1.3中，指定好路線圖的環境背景。一家公司應該要有清晰的愿景（Vision），且技術路線圖應該要能清楚地支持此愿景。如果愿景不存在，那么應該先發展出一個愿景，并清晰地描述它。當做到這一點，路線圖的邊界與范圍就能夠被定義出來。此外，還要設定好計劃區間和詳細程度。
完成了第一階段的初步行動，接下來就可以進行第二階段，真正把技術路線圖開發出來。第二階段可以分成七個步驟，下面依次描述。
2.1 找出路線圖焦點的產品：在本步驟中，找出共通的產品需求，且所有的參與者對此達成共識。讓所有的人都能接受此步驟相當重要。如果有不確定的地方，可以采用場景規劃（scenario-based planning）的方式，找出共通的產品需求；
2.2 找出關鍵的系統需求以及它們的目標：一旦決定好，這些需求要被設定路線，然后關鍵的系統需求就可以被辨識出來。關鍵的系統需求為技術路線圖提供整體的框架。這里的需求可以有一些目標（例如高穩定性、低成本）；
2.3 指定主要的技術領域：想實現此關鍵的系統需求，有一些相關的領域。對于每個技術領域而言，有一些技術在其中。技術領域包括分布式數據庫、網絡、系統開發、財務會計等；
2.4 指定技術者和他們的目標：在此步驟中，來自步驟2.2的關鍵系統需求會被轉換成某技術領域中具有目標的技術驅動者（technology driver）。這些驅動者會影響那些技術方案被選用。驅動者依賴于技術領域，但是與“技術如何因應系統需求”有關；
2.5 找出技術方案與它們的時間線：此時技術驅動者和它們的目標已經被指定好，且“滿足目標的技術方案”應該也被指定好。對于每個技術方案，都應該估計出一個時間線，說明它會如何成型，以符合技術驅動者的目標。某些特定的狀況下，要考慮到時間。電子商務或軟件開發的區間通常會比較短；
2.6 建議應該采用的技術方案：因為不同技術方案的成本、時間線等條件可能不同，所以要從中做選擇。在這個步驟，要根據目標做取舍（例如：效能比成本重要）；
2.7 建議技術路線圖報告：此時技術路線圖已經完成。技術路線報告包含五個部分的內容（當然，此報告也可以包含其他額外的資訊）：
- 每個技術領域的識別與描述；
- 路線圖的關鍵因素；
- 未處理的領域；
- 實踐的建議；
- 技術建議。
完成了2.1~2.7的七個步驟，技術路線圖就已經開發出來了。軟件開發出來并不代表結束，還需要后續的測試、運營、維護等。同理，技術路線圖開發出來之后（第二階段），還需要后續的動作（第三階段）。
第三階段大致分為三個步驟：
- 3.1 討論和驗證路線圖：路線圖需要被批評、驗證、采用；
- 3.2 制訂一個執行計劃：要依據技術路線圖設計出一個計劃；
- 3.3 審查和更新：要周期性的審查并更新。
總結
本系列文章共四篇，到此已經完全結束。通過本系列文章，希望喚醒大家對技術文檔的重視。
技術寫作的經驗培養、技術文檔體系的建立，都是需要時間的。身為一個技術人員，如果你認為你正在做的技術是有價值的，你就應該為它建立技術文檔，盡管一開始會覺得寫作很難、也沒足夠的時間進行寫作。公司更應該領悟到，如果沒有技術文檔，一旦人員更替、新員工加入，或者需要對外推廣時，都會遇到相當多的困難。從今天起，讓我們開始重視技術寫作能力的培養與技術文檔體系的建立。
作者簡介：
蔡學鏞，臺灣臺南人，畢業于臺灣清華大學Computer Science研究所，現任阿里巴巴支付寶架構師，負責新系統的開發。
it知識庫：蔡學鏞：架構師最重視的文檔，轉載需保留來源！
鄭重聲明：本文版權歸原作者所有，轉載文章僅為傳播更多信息之目的，如作者信息標記有誤，請第一時間聯系我們修改或刪除，多謝。
