2010-08-18 11:28:41 來源：《程序員》
技術(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ù)營(yíng)銷的手段之一，它的目的是幫助讀者了解技術(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ù)營(yíng)銷”的文件，適合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)，不可以長(zhǎng)篇大論；
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不長(zhǎng)，沒有必要提供目錄。
·內(nèi)容：依據(jù)上面述的六個(gè)重點(diǎn)編寫，格式自由安排。下面是建議內(nèi)容：
摘要（約中文三百字的摘要）
簡(jiǎn)介（What、Why、How等）
技術(shù)說明（架構(gòu)等）
Summary（總結(jié)）
文檔的法律聲明
技術(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è)績(jī)，需要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è)階段：
1. 第一階段：初步行動(dòng)；
2. 第二階段：技術(shù)路線圖開發(fā)；
3. 第三階段：后續(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ù)路線圖所需、來自組織不同部門（營(yíng)銷、開發(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)營(yíng)、維護(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é)
技術(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ù)文檔體系的建立。
（責(zé)編：陳廣成）
免責(zé)聲明：本網(wǎng)站（http://www.www.gypb.net/）內(nèi)容主要來自原創(chuàng)、合作媒體供稿和第三方投稿，凡在本網(wǎng)站出現(xiàn)的信息，均僅供參考。本網(wǎng)站將盡力確保所提供信息的準(zhǔn)確性及可靠性，但不保證有關(guān)資料的準(zhǔn)確性及可靠性，讀者在使用前請(qǐng)進(jìn)一步核實(shí)，并對(duì)任何自主決定的行為負(fù)責(zé)。本網(wǎng)站對(duì)有關(guān)資料所引致的錯(cuò)誤、不確或遺漏，概不負(fù)任何法律責(zé)任。
本網(wǎng)站刊載的所有內(nèi)容（包括但不僅限文字、圖片、LOGO、音頻、視頻、軟件、程序等）版權(quán)歸原作者所有。任何單位或個(gè)人認(rèn)為本網(wǎng)站中的內(nèi)容可能涉嫌侵犯其知識(shí)產(chǎn)權(quán)或存在不實(shí)內(nèi)容時(shí)，請(qǐng)及時(shí)通知本站，予以刪除。
搶沙發(fā)
