軟體架構文件(SAD)實戰 – 1.排版與畫圖


因為最近在教如何寫:軟體架構文件 software architecture document(SAD),所以開始寫這一系列的文章。(不知道寫不寫得完……)

我一直認為,好的工程師是會寫文件的,SA/SD要很會寫,軟體架構師更是要超會寫,但要寫得有組織架構,條理分明,面面俱到的文件,卻是不容易的,在此將個人的寫文件經驗分享出來。

在這邊不用去爭論什麼文件無用論,無用是因為你不會用,你說文件內容與實際執行不準確,那是因為:
1.組織中沒有技術主編,或是專門人員在review文件內容。
2.沒有文件管理流程,導致文件與現實差距過大。

但我還是建議要學會寫文件的技巧,寫文件的過程本身就是一種設計或是review的過程。

你更要學的是:如何避免寫出沒有用的文件。

開始前的準備:

工具:這是一致性的問題。

選擇.doc或是.html;繪圖工具使用Visio還是Word/PowerPoint;UML使用Enterprise Architecture還是StarUML;單獨用或是混和用?

除了文件格式是一開始就要決定的,其他的越早決定越好。

排版:Word樣式/ CSS

這真的很重要,使用.doc的話,請一開始就提供 dot的範本檔,其中標題一、二、三、四的字體大小、格式、顏色都是一開始就要訂的,寫程式的通常還要來個程式碼的樣式,像下面的範例:
01

頁首頁尾、圖/表書寫格式也通通不能少,請認真地去看侯大師的word排版藝術,若是你是一個架構師,請注意,你必然少不掉要review很多文件,賞心悅目的排版會讓你比較好review下去。

CSS 當然也是比照辦理。

繪圖:圖的格式 / 顏色

這個很難,你很難教導大家的圖解都是乾淨俐落,言之有物的,所謂的意圖這件事,我稍後會講到。

不過最基本的格式、顏色總是要規範的,我最常遇到的就是,這張圖示中的黃色是表示A系統,但同一層級的B系統卻是使用綠色之類的,這樣會讓人混淆的,顏色也不要使用太多,像下圖所示:
Concept1
注意到圖中下面的一個重點就是,你有將使用的顏色代表的涵義說明出來;當然若是使用不同的圖形(圓形/三角形),也請記得做圖示說明。

另外很多類似的表示圖示,也需統一用的時機,像表示人的圖像可能有下列幾種:

Concept1 但不要一張圖出現好幾種人示,可以用文字或顏色分辨即可。
為求統一,也必須說明什麼圖形什麼顏色是表示什麼。

當然,習慣法 / 專用語也是必然要一致的,有機會我們在說明SA時會在Glossary章節再講。

文件版本控制:這是一個大問題,文件交換通常都是copy來copy去的,結果大家在溝通時,常常牛頭不對馬嘴,因為看到的是不同的版本;當然我們可以使用CVS、SVN之類的版本控管,或是KM、目錄分享的方式,做到”盡量”大家拿到的都是同一版本的文件,可是merge時又是一個大問題。

但要秉持一個原則:文件的reference只有一個。

也就是大家都說好,不管怎麼copy,反正就是以那個位置的文件為主要參考。未更新則是個人的責任。

像我們使用Google docs來處理這個問題,永遠只有一份參考,也只共同編輯這一份。

建議要有一個技術主編(同常也是架構師啦),可以由主編指派個人寫的每一小章節,再予以統合,這樣才能保證文件的一致性以及品質。

繪圖

技術文件中,畫圖是一件困難的事,因為,我們從未被好好地教導過如何畫圖這件事。

也因此,一張圖當中常常顯示了太多的訊息,這樣導致看圖的人不見得能清楚地接收你在圖中想傳達的訊息。

一圖勝千言。

沒經驗的人通常就是想到什麼畫什麼,一張圖塞得滿滿的,好像全部都說到了,就自以為交待清楚了。

那看圖的人就很可憐了,全部都在一張圖裡面找線索;這也不是說不行,反正最後大家都有得到所要的資訊就是了,只是溝通成本會增加很多。

這跟藝術上構圖是相同的,盡可能讓一張圖只有 1~2個要凸顯的目的。

要記得,說太多等於沒說。

所以第一件要做的就是:分類

不同的訊息放在不同的圖。

搞過房子裝潢的就知道,通常除了隔間的圖外,還有插座配置、燈具配置、水管口……好幾張圖,都是分開畫,給不同的師傅看的時候用。

之後我們會提到,這就是”View”的用法。

注意,我們需要從不同的視野來看同一件事,不同的圖給不同的相關者看。

01接這就是分層

原則就是由大而小。

相同level的組件就放在同一張圖講,也就是要去定義這張圖要說明到level幾。

要就統一到level 2 ,那麼A組件的level3相關部分,再有一張A組件的全圖去看。

不要A組件顯示到level3的層級,B組件卻只到level 2;當然這不是絕對的,有的時候因為有的東西太重要,所以有跳層級被凸顯的必要。

但一層層的寫法是寫文件的必要思考。

最後就是要使用對的圖來表達。

善用各種圖示法,UML沒有想像中的神,如果UML很難表達,就換個圖。

不是說你多會畫,而是這張圖的”意圖”是否被表達出了。

相同含意的圖,用visio的小人頭流程圖可能會比activity diagram好讀,但不是每個team member都懂 UML的,且還要再考慮到一個domain因素:也就是大家剛開始做這案子的時候,對domain都是不熟的。

很快進入狀況是比較重要的事,圖的重點是拿來溝通用的,也就是可能剛開始先用visio劃出比較大流程之類的圖,之後在SA/SD的文件部分再改成使用AD。

當然,若是團隊中的每個人都熟悉UML的意含了,就統一使用更好。(有機會我們再來講畫 UML的規範,有興趣的可以先去看The Elements of UML 2.0 Style)

其他還有DFD、flowchart、ERD、fishbone、process…… ,當然,不要什麼圖都拿來用,要因時、因材使用。


轉載請註明出處。 krilo cheng

3 意見:

匿名 提到...

我想知道那些圖是哪個工具的, 滿漂亮的

krilo 提到...

呵呵 , 使用ConceptDraw Office畫的~

匿名 提到...

好文章!謝謝您!