通向架構(gòu)師的道路——漫談架構(gòu)與設(shè)計(jì)文檔的寫作技巧

前言：

這篇是一篇番外篇，沒有太多代碼與邏輯，完全是一種”軟“技巧，但是它對(duì)于你如何成為一名合構(gòu)的架構(gòu)設(shè)計(jì)人員很重要。

在此要澄清一點(diǎn)，架構(gòu)師本身也是”程序員“，不是光動(dòng)嘴皮子的家伙們，如果你不是一名程序雖出身那你根本談不上也不可能成為一名架構(gòu)師。

那么架構(gòu)師還有哪些是作為一名程序員來說不具備的呢？

其中有一項(xiàng)能力就叫做”文檔寫作能力“。

一、Soft Skill與Hard Skill

作為一名架構(gòu)師除了是一名資深的程序員外，它還必須具有相應(yīng)的Soft Skill，其中有一名就叫做Documentation Skill。

1. 先來說一下Hard Skill

代碼與框架以及產(chǎn)品的靈活使用以及在相應(yīng)的domain（如Insurance, Banking, CRM, DW。。。）上的經(jīng)驗(yàn)我們把它稱為Hard Skill，沒有這些技巧你就成不了一名合格的程序員。

程序員和IT是有區(qū)別的，程序員是IT業(yè)內(nèi)的主力軍團(tuán)，但是如果你是在一家網(wǎng)站或者是軟件司作需求分析的，哪怕是一個(gè)秘書，那你也是一個(gè)IT人員，對(duì)吧？所以這些東西是一個(gè)成為架構(gòu)師的“硬”條件。

2. 什么是Soft Skill

Soft Skill即指Documentation Skill, Presentation Skill，Communication Skill, 相應(yīng)的Language Skill（不包括日本語，BS小日本）, Management Skill, Leader Ship, 這些.

當(dāng)然，還有更多，更多。。。

2.1 Documentation Skill與Presentation Skill

今天主要講述的是Documentation Skill與Presentation Skill。

勿要小看這兩點(diǎn)，有人說他自己編程編得好，有人說自己的算法寫了如何如何精深，那么。。。在現(xiàn)在這個(gè)團(tuán)隊(duì)合作至上以及處于目前這樣的世界經(jīng)濟(jì)大環(huán)境以客戶至上的背景下你所知道的的東西不能向其它人表達(dá)清楚，誰會(huì)理解你的想法，誰會(huì)接受你的理念，誰會(huì)選擇你公司的產(chǎn)品呢？

舉兩個(gè)例子：

蘇步青，他是大數(shù)學(xué)家，對(duì)吧，或許不少人不知道蘇步青在文學(xué)上的造詣也是很深的。

蘇步青曾說過：為什么我喜歡語文，語言，因?yàn)槲业恼撐?，我的教材需要用語言去表達(dá)的，如果不把語言，語文學(xué)好我根本無法更精準(zhǔn)更明白的去表達(dá)我的算法。

著名計(jì)算機(jī)學(xué)者C語言教程的作者譚好強(qiáng)曾經(jīng)說過：能夠把復(fù)雜的問題用簡單直白的語言和框圖去表達(dá)出來，就是最好的論文。

再說個(gè)實(shí)際點(diǎn)的例子，你處于一個(gè)投標(biāo)競賽中，你的設(shè)計(jì)或許是很好，可是如何讓客戶能夠理解和接受貴公司的設(shè)計(jì)方案呢？

那么你需要在平時(shí)有意識(shí)的去提高或者我們說修練一下你的documentation skill，documentation skill與presentation skill是聯(lián)系在一起的.

2.2 要善于懂得“包裝”

Presentation Skill即”宣傳、演示、演講、推銷"的一種技巧，很多人在面對(duì)你的同事或者朋友時(shí)可能會(huì)滔滔而談，但是在面對(duì)你的上司或者是在客戶面前，就成了“縮貨”了。。。為什么？

其實(shí)很多時(shí)候在于你演講的底稿我們一般用PPT或者是WORD準(zhǔn)備的不足，呆板、凡味，還有時(shí)在于你的設(shè)計(jì)確實(shí)自己也拿捏不準(zhǔn)。

因此Hard Skill是你的底氣，有了足夠硬的Hard Skill你有了50%的膽子再加上一篇好的Document（PPT一類）你的另50%膽子也有了，此時(shí)你的Presentation Skill就提升了.

所以很多時(shí)候你的Presentation Skill是等于Hard Skill+Documentation Skill的。

有一部片叫《幸德勒的名單》相信不少人看過吧？開頭30分鐘，靠著不足萬元“老本”的幸德勒來到了猶太人聚集地，找到了猶太會(huì)計(jì)師-以撒.斯坦，他滔滔而談自己成立公司的計(jì)劃，如何可以掙錢。然后以撒.斯坦問了他一句：

請(qǐng)讓我弄明白一件事，我出人，然后我找”金主“出錢，那你出什么。。。？

幸德勒吸了一口煙，雙手合在一起后向外一推 ”presentation, 這是我最擅長的“，這邊的presentation也可認(rèn)為是一種包裝.

同樣一個(gè)中國生產(chǎn)的杯子和美國，如果性能、功能、使用壽命都一樣，相信一定是美國貨賣得貴，為什么？因?yàn)樗谟辛薍ard Skill基礎(chǔ)上再次進(jìn)行了”包裝“，這就是”好萊塢式"的促銷手法。

要學(xué)會(huì)“包裝”但不是扯蛋和吹牛，因?yàn)榧軜?gòu)師拿出來的東西哪怕再漂亮，如果沒有內(nèi)含那也是“濫竽充數(shù)”，被人識(shí)破后就一錢不值了。但是我們在有好的質(zhì)量好的技術(shù)的基礎(chǔ)上善于去“包裝”它，相信你會(huì)離成功更近一步。

三、如何寫好一篇文檔和提高你的documentation skill

我在前公司有一陣沒空，一度讓其它幾個(gè)senior的Team Leader幫助我寫文檔，要求把設(shè)計(jì)按照需求能夠?qū)懬寮纯伞?/p>

送上來5篇文章，基本一篇都不能用.

第一次送上來，每篇都是講一個(gè)功能點(diǎn)，要不是冗長的一段沒意義的解釋，要不就是從官網(wǎng)直接COPY一段話下來，甚至連1,2,3,4都沒列出來，至少你要有個(gè)Advantage Points 或者說是Benefit和Disadvantage Points的對(duì)比吧.

第二次送上來，有了1，2，3，4，但是這下好了，全都標(biāo)成1,2,3,4了。

要善于利用office編輯器中的“符號(hào)列表”，“4角星”代表亮點(diǎn)，“√"代表優(yōu)點(diǎn)，”小點(diǎn)點(diǎn)“放在段落前用來將功能點(diǎn)說明”分層“，使閱話者更清晰.

這樣說吧，你把自己當(dāng)成一個(gè)閱讀者了嗎？對(duì)吧？

3.1 一圖勝千言

我們在描述一個(gè)審計(jì)日志功能模塊時(shí)我們說用Spring做，如果能夠附上下面這樣的一張圖是不是會(huì)更加生動(dòng)呢？

一個(gè)架構(gòu)文檔，從基本的來講需要有：

• Logic View（邏輯視圖）

• Physical View（物理視圖）

• Network Structure（網(wǎng)絡(luò)拓卜圖）

• Workflow/Process Flow（流程圖）

你在描述你的流程時(shí)你怎么表達(dá)你的if else if else，對(duì)吧？有個(gè)流程圖是不是會(huì)更好讓人懂你所描述的這個(gè)流程是一個(gè)什么樣子的呢？

那我畫個(gè)流程圖去。。。畫啊畫，畫完后拿過來一看：

黑線框、框內(nèi)有幾個(gè)字，幾個(gè)帶箭頭的線連一下。。。不錯(cuò)。。。是畫對(duì)了，可是你有沒有想過，有些業(yè)務(wù)場景中流程圖往往還要表達(dá)不同的”業(yè)務(wù)邊界“啊。。。

拿下面的一個(gè)圖來說，是不是這樣的表達(dá)比只有黑框框+帶箭頭的線+幾個(gè)文字更加易懂啊？

3.2 畫好你的圖

3.2.1 架構(gòu)圖的配色與表達(dá)手法

不要認(rèn)為畫圖是”美工“的事，你是設(shè)計(jì)人員，你是架構(gòu)師，畫好一個(gè)應(yīng)用圖是你的本職工作，圖中需要什么圖標(biāo)可以把你的需求告訴美工，美工再會(huì)去處理。

一般來說，我們?yōu)榱吮磉_(dá)一個(gè)系統(tǒng)的模塊組成，我們通常會(huì)用：component view來表達(dá)如下面這樣的圖

這個(gè)被稱為”自上而下“的一個(gè)平面圖，用于表示”服務(wù)邊界“

、

如果你考究的話還可以提供一個(gè)”剖視圖“，如典型的用于表示詳細(xì)業(yè)務(wù)組件的”側(cè)面剖視圖“：

這種Component View一般都是跟著你的總架構(gòu)圖和網(wǎng)絡(luò)拓卜圖的后面出現(xiàn)的，這三套圖我稱它為“炮鳴三聲”（起兵啦。。。）。

因此這樣的圖往往會(huì)使用“暖色調(diào)”，以幾何或者立體的色塊來展現(xiàn)，帶給觀看者強(qiáng)烈的視覺沖擊，架構(gòu)師的功底基本可以集中體現(xiàn)在這三套圖中，這三套圖同時(shí)也起到了“先聲奪人”吸引觀眾的眼球，注意力的作用（那邊的女孩看過來看過來，我的鈔票多。。。嘿嘿嘿）

如下面這樣的一個(gè)總架構(gòu)圖的表現(xiàn)手法：

對(duì)吧，暖色調(diào)，以幾何或者立體的色塊來展現(xiàn)

3.2.2 以圖繪意

我這邊提個(gè)問題：如何表達(dá)一個(gè)”業(yè)務(wù)規(guī)則“，如何去表達(dá)一個(gè)”工作流“，就是”業(yè)務(wù)規(guī)則“這四個(gè)字我用圖怎么表達(dá)。。。工作流這三個(gè)字我用圖怎么表達(dá)？大家想一下。

來，看看下面的圖：

這個(gè)圖一看就知道是在表達(dá)process或者說是工作流

這個(gè)圖代表”規(guī)則“，規(guī)則就是一組if else if if

對(duì)吧。?！，F(xiàn)在來個(gè)更難的，我的業(yè)務(wù)規(guī)則用的是規(guī)則引擎，且內(nèi)核是jboss rulz，嘿嘿，怎么用圖標(biāo)達(dá),來。。。下面給出我的答案：

對(duì)吧。。?？吹搅藛帷?。。圖用來繪意，但圖不能亂用，就拿這個(gè)”系統(tǒng)中使用了JBOSS? RULZ來作為規(guī)則引擎"這個(gè)描述來說，你要畫的圖其實(shí)是建立在你的Hard Skill上的。

3.2.3 依照“八股文”來繪制設(shè)計(jì)圖

八股文就是有條理有章矩，不管什么樣的文章你按照八股文去寫，寫出來都是一樣的層次，我們考四級(jí)英語的“寫作”這一本時(shí)其實(shí)也是有“章法”可循的對(duì)吧？

那么這個(gè)設(shè)計(jì)圖的畫法也是有章可循的，也是有它的“八股文”樣板的。

前面說了，上手三套圖先聲奪人，搶人二目，那么在架構(gòu)設(shè)計(jì)文檔中還會(huì)充質(zhì)著種種模塊，子模塊，功能設(shè)計(jì)，功能點(diǎn)描述圖。。。如果你也來個(gè)一概而論，那就不是先聲奪人了，而是“喧賓奪主“了，呵呵呵。

這種子模塊、功能設(shè)計(jì)或者是功能點(diǎn)描述往往往以點(diǎn)、線為主，以點(diǎn)、線來連成一個(gè)面，而面中”婁空“，如下面的樣例:

四、如何畫出準(zhǔn)確且“漂亮”的設(shè)計(jì)圖呢

七叔：You are beautiful...啊...you are beautiful...You are so handsome...啊You are so handsome...

周星星：七叔，你不要這樣好吧。。。七叔。。。來人啊。。。

我在前一天即第二十五天中用來描述DbUnit的優(yōu)點(diǎn)時(shí)用到了一套圖，它們是這樣的，大家還記得吧？

右邊的文字，沒什么稀罕的，都是配色而己，關(guān)鍵在于左邊的這個(gè)圖。。。hoho，很多人問我用的是什么工具畫的？

我告訴你們，我不是美工，我其實(shí)是在“拼圖”，如這幅圖的制作：

我是用了以下這5幅小圖標(biāo)，拼制而成的：

不是這么簡單的，隨便畫畫就成了，都要花功夫的、花心思去制作的。

• 平時(shí)自己看到好的可以表達(dá)某個(gè)意義的圖片，存下來，分門別類

• 看到人家寫的好的架構(gòu)文檔，存下來，看看人家是怎么去描述一個(gè)功能點(diǎn)的

• 多搜集一些IT上專用的圖標(biāo)，小圖片，logo

IBM的文檔是我看到過最恐怖的文檔，基本上這里面的架構(gòu)文檔出來都一個(gè)腔調(diào)，沒什么文字，都是圖，連個(gè)“登錄過程”都用圖表達(dá)，連個(gè)“源碼check in check out”的管理流程都用圖表達(dá)。

保持你的圖系一致及風(fēng)格的一致，你可以用卡通系、商務(wù)系任何一個(gè)系的圖來表達(dá)你的設(shè)計(jì)思想，但是當(dāng)你的第一幅圖用的就是哪個(gè)系時(shí)，你的文檔中所有的圖都請(qǐng)用這個(gè)系列，而不建議你混雜使用你的圖系。

五、圖文混雜的技巧

什么都不多說，上截圖，大家自己去感受一下吧

今天就說這么多，希望對(duì)大家提高你的設(shè)計(jì)文檔寫作水平有所提高吧。

點(diǎn)擊獲取?附送學(xué)習(xí)進(jìn)階架構(gòu)資料、PDF書籍文檔、面試資料