文/蔡學(xué)鏞

　　技術(shù)文檔很多，每種文檔都有各自的目的。其中和架構(gòu)師關(guān)系最密切的、甚至架構(gòu)師應(yīng)該親自寫的文檔是技術(shù)白皮書與技術(shù)路線圖，這兩份文檔是本次文章的重點(diǎn)。

　　技術(shù)白皮書

　　White Paper衍生自White Book（白皮書），一般也稱為白皮書，但是內(nèi)容更濃縮、更精華。White Paper通常合起來寫為Whitepaper。

　　技術(shù)白皮書（Technical White Paper）是官方正式的報(bào)告指南，風(fēng)格介于技術(shù)論文和商業(yè)雜志文章之間，用來描述大問題和技術(shù)解決方案。技術(shù)白皮書是常用的技術(shù)營銷的手段之一，它的目的是幫助讀者了解技術(shù)、做出決策。技術(shù)白皮書通常是以PDF文件格式存在，10頁左右的篇幅最恰當(dāng)。

　　技術(shù)發(fā)明者（或擁有者）才能發(fā)表技術(shù)白皮書。例如，支付寶可以發(fā)表“總督系統(tǒng)”技術(shù)白皮書（我正在研發(fā)的一套CEP系統(tǒng)），但不可以發(fā)表Spring框架技術(shù)白皮書。支付寶計(jì)劃走向開放，未來可能會(huì)提供開放API，那時(shí)候就可以對(duì)外推出技術(shù)白皮書。

　　技術(shù)白皮書是“技術(shù)營銷”的文件，適合CTO、技術(shù)總監(jiān)、技術(shù)專家之類的高層決策人士閱讀，讓他們通過“大局觀”的方式了解整個(gè)技術(shù)概況。技術(shù)白皮書的重點(diǎn)在于讓讀者深刻理解采用此技術(shù)將為他們帶來多大的利益。

　　編寫技術(shù)白皮書要把握以下重點(diǎn)：

1. 技術(shù)白皮書代表官方，所以敘述風(fēng)格必須具有權(quán)威性；
2. 良好的技術(shù)白皮書通常會(huì)附上許多方塊圖，將技術(shù)內(nèi)部的結(jié)構(gòu)表達(dá)清楚，并說明和外部的關(guān)系；
3. 如果無法使用示意圖時(shí)，盡量使用Bullet Point；
4. 技術(shù)白皮書一定要把握重點(diǎn)，不可以長篇大論；
5. 技術(shù)白皮書一定要有高技術(shù)含量，雞毛蒜皮的瑣碎細(xì)節(jié)一概不提；
6. 以讀者的利益為敘述核心，而非以技術(shù)本身的先進(jìn)或自身的利益為敘述核心。

　　上面的第6點(diǎn)是大部分技術(shù)白皮書的毛病所在，需要特別解釋。技術(shù)白皮書不應(yīng)該淪為自言自語、自吹自捧，而是應(yīng)該從“顧客第一”的角度分析讀者有什么問題，需要什么樣的技術(shù)，而我們的技術(shù)可能是一項(xiàng)不錯(cuò)的解決方案，因?yàn)槲覀兪侨绾稳绾巫龅降摹?/p>

　　我建議的技術(shù)白皮書編寫框架如下：

• 封面：技術(shù)名稱、縮寫、版本；公司名稱、Logo；文檔日期。
• 不需要目錄，因?yàn)槲臋n不長，沒有必要提供目錄。
• 內(nèi)容：依據(jù)上面述的六個(gè)重點(diǎn)編寫，格式自由安排。下面是建議內(nèi)容：

1. 摘要（約中文三百字的摘要）
2. 簡介（What、Why、How等）
3. 技術(shù)說明（架構(gòu)等）
4. Summary（總結(jié)）
5. 文檔的法律聲明

　　技術(shù)路線圖

　　討論完技術(shù)白皮書，接下來看技術(shù)路線圖（Technology Roadmap）。

　　想要到達(dá)某個(gè)目標(biāo)，可能不是一蹴而就的事，需要有路線規(guī)劃，讓大家一目了然地知道近期、中期、遠(yuǎn)期的目標(biāo)，這就是Roadmap（路線圖）。Roadmap也可以寫成Road Map。

　　Roadmap 應(yīng)用相當(dāng)廣泛：兩岸想統(tǒng)一，需要Roadmap；支付寶想要?jiǎng)?chuàng)造100倍的業(yè)績，需要Business Roadmap。如果過程涉及技術(shù)，那么這就是 Technology Roadmap。只有新產(chǎn)品、新興技術(shù)、相當(dāng)復(fù)雜的產(chǎn)品可以有Technology Roadmap。如果僅是對(duì)產(chǎn)品做小改進(jìn)，根本不需要Technology Roadmap。

　　技術(shù)路線圖有三個(gè)主要用途：

• 是一種規(guī)劃，幫助決定出一組需求，以及滿足此需求的技術(shù)；
• 是一種機(jī)制，可以幫助預(yù)測(cè)技術(shù)開發(fā)與走向；
• 是一種框架，可以用來幫助計(jì)劃與協(xié)調(diào)技術(shù)的開發(fā)。

　　隨著軟件產(chǎn)業(yè)越來越成熟，產(chǎn)品經(jīng)理（Product Manager）也變成必備的職位。產(chǎn)品經(jīng)理要負(fù)責(zé)整個(gè)開發(fā)過程的管理，在此過程中，制定產(chǎn)品路線可以幫助軟件產(chǎn)品經(jīng)理規(guī)劃與分配資源。

　　制定技術(shù)路線圖分三個(gè)階段：

• 第一階段：初步行動(dòng)；
• 第二階段：技術(shù)路線圖開發(fā)；
• 第三階段：后續(xù)行動(dòng)。

　　可以看出第一階段是準(zhǔn)備，第二階段是重點(diǎn)，第三階段是后續(xù)跟蹤修改。

　　在第一階段（初步行動(dòng)），關(guān)鍵決策者發(fā)現(xiàn)他們有一個(gè)問題需要解決，而需要一份技術(shù)路線圖來幫助他們解決此問題，他們要這樣做：

• 1.1 滿足根本條件；
• 1.2 賦予領(lǐng)導(dǎo)權(quán)威或地位；
• 1.3 定義技術(shù)路線范圍和邊界。

　　在步驟1.1中，條件包含技術(shù)路線圖所需、來自組織不同部門（營銷、開發(fā)、戰(zhàn)略等部門）的輸入，這些部門有著不同的計(jì)劃區(qū)間（Planning Horizon）和不同的看事情角度。如果條件不滿足，則要采取行動(dòng)來滿足條件。條件都滿足了，才能繼續(xù)下一個(gè)步驟。

　　步驟1.2的意思是：技術(shù)路線圖的建立牽涉到時(shí)間和各種資源，必須要有堅(jiān)定的領(lǐng)導(dǎo)權(quán)威。領(lǐng)導(dǎo)權(quán)威必須來自參與者之一，由參與者之一賦予領(lǐng)導(dǎo)權(quán)威或地位。讓組織驅(qū)動(dòng)此過程，并使用此路線圖來進(jìn)行資源分配的決策。

　　在步驟1.3中，指定好路線圖的環(huán)境背景。一家公司應(yīng)該要有清晰的愿景（Vision），且技術(shù)路線圖應(yīng)該要能清楚地支持此愿景。如果愿景不存在，那么應(yīng)該先發(fā)展出一個(gè)愿景，并清晰地描述它。當(dāng)做到這一點(diǎn)，路線圖的邊界與范圍就能夠被定義出來。此外，還要設(shè)定好計(jì)劃區(qū)間和詳細(xì)程度。

　　完成了第一階段的初步行動(dòng)，接下來就可以進(jìn)行第二階段，真正把技術(shù)路線圖開發(fā)出來。第二階段可以分成七個(gè)步驟，下面依次描述。

　　2.1 找出路線圖焦點(diǎn)的產(chǎn)品：在本步驟中，找出共通的產(chǎn)品需求，且所有的參與者對(duì)此達(dá)成共識(shí)。讓所有的人都能接受此步驟相當(dāng)重要。如果有不確定的地方，可以采用場(chǎng)景規(guī)劃（scenario-based planning）的方式，找出共通的產(chǎn)品需求；

　　2.2 找出關(guān)鍵的系統(tǒng)需求以及它們的目標(biāo)：一旦決定好，這些需求要被設(shè)定路線，然后關(guān)鍵的系統(tǒng)需求就可以被辨識(shí)出來。關(guān)鍵的系統(tǒng)需求為技術(shù)路線圖提供整體的框架。這里的需求可以有一些目標(biāo)（例如高穩(wěn)定性、低成本）；

　　2.3 指定主要的技術(shù)領(lǐng)域：想實(shí)現(xiàn)此關(guān)鍵的系統(tǒng)需求，有一些相關(guān)的領(lǐng)域。對(duì)于每個(gè)技術(shù)領(lǐng)域而言，有一些技術(shù)在其中。技術(shù)領(lǐng)域包括分布式數(shù)據(jù)庫、網(wǎng)絡(luò)、系統(tǒng)開發(fā)、財(cái)務(wù)會(huì)計(jì)等；

　　2.4 指定技術(shù)者和他們的目標(biāo)：在此步驟中，來自步驟2.2的關(guān)鍵系統(tǒng)需求會(huì)被轉(zhuǎn)換成某技術(shù)領(lǐng)域中具有目標(biāo)的技術(shù)驅(qū)動(dòng)者（technology driver）。這些驅(qū)動(dòng)者會(huì)影響那些技術(shù)方案被選用。驅(qū)動(dòng)者依賴于技術(shù)領(lǐng)域，但是與“技術(shù)如何因應(yīng)系統(tǒng)需求”有關(guān)；

　　2.5 找出技術(shù)方案與它們的時(shí)間線：此時(shí)技術(shù)驅(qū)動(dòng)者和它們的目標(biāo)已經(jīng)被指定好，且“滿足目標(biāo)的技術(shù)方案”應(yīng)該也被指定好。對(duì)于每個(gè)技術(shù)方案，都應(yīng)該估計(jì)出一個(gè)時(shí)間線，說明它會(huì)如何成型，以符合技術(shù)驅(qū)動(dòng)者的目標(biāo)。某些特定的狀況下，要考慮到時(shí)間。電子商務(wù)或軟件開發(fā)的區(qū)間通常會(huì)比較短；

　　2.6 建議應(yīng)該采用的技術(shù)方案：因?yàn)椴煌夹g(shù)方案的成本、時(shí)間線等條件可能不同，所以要從中做選擇。在這個(gè)步驟，要根據(jù)目標(biāo)做取舍（例如：效能比成本重要）；

　　2.7 建議技術(shù)路線圖報(bào)告：此時(shí)技術(shù)路線圖已經(jīng)完成。技術(shù)路線報(bào)告包含五個(gè)部分的內(nèi)容（當(dāng)然，此報(bào)告也可以包含其他額外的資訊）：

• 每個(gè)技術(shù)領(lǐng)域的識(shí)別與描述；
• 路線圖的關(guān)鍵因素；
• 未處理的領(lǐng)域；
• 實(shí)踐的建議；
• 技術(shù)建議。

　　完成了2.1~2.7的七個(gè)步驟，技術(shù)路線圖就已經(jīng)開發(fā)出來了。軟件開發(fā)出來并不代表結(jié)束，還需要后續(xù)的測(cè)試、運(yùn)營、維護(hù)等。同理，技術(shù)路線圖開發(fā)出來之后（第二階段），還需要后續(xù)的動(dòng)作（第三階段）。

　　第三階段大致分為三個(gè)步驟：

• 3.1 討論和驗(yàn)證路線圖：路線圖需要被批評(píng)、驗(yàn)證、采用；
• 3.2 制訂一個(gè)執(zhí)行計(jì)劃：要依據(jù)技術(shù)路線圖設(shè)計(jì)出一個(gè)計(jì)劃；
• 3.3 審查和更新：要周期性的審查并更新。

　　總結(jié)

　　本系列文章共四篇，到此已經(jīng)完全結(jié)束。通過本系列文章，希望喚醒大家對(duì)技術(shù)文檔的重視。

　　技術(shù)寫作的經(jīng)驗(yàn)培養(yǎng)、技術(shù)文檔體系的建立，都是需要時(shí)間的。身為一個(gè)技術(shù)人員，如果你認(rèn)為你正在做的技術(shù)是有價(jià)值的，你就應(yīng)該為它建立技術(shù)文檔，盡管一開始會(huì)覺得寫作很難、也沒足夠的時(shí)間進(jìn)行寫作。公司更應(yīng)該領(lǐng)悟到，如果沒有技術(shù)文檔，一旦人員更替、新員工加入，或者需要對(duì)外推廣時(shí)，都會(huì)遇到相當(dāng)多的困難。從今天起，讓我們開始重視技術(shù)寫作能力的培養(yǎng)與技術(shù)文檔體系的建立。

　　作者簡介：

　　蔡學(xué)鏞，臺(tái)灣臺(tái)南人，畢業(yè)于臺(tái)灣清華大學(xué)Computer Science研究所，現(xiàn)任阿里巴巴支付寶架構(gòu)師，負(fù)責(zé)新系統(tǒng)的開發(fā)。

it知識(shí)庫：蔡學(xué)鏞：架構(gòu)師最重視的文檔，轉(zhuǎn)載需保留來源！

鄭重聲明：本文版權(quán)歸原作者所有，轉(zhuǎn)載文章僅為傳播更多信息之目的，如作者信息標(biāo)記有誤，請(qǐng)第一時(shí)間聯(lián)系我們修改或刪除，多謝。