因為最近在教如何寫:軟體架構文件 software architecture document(SAD),所以開始寫這一系列的文章。(不知道寫不寫得完……)
我一直認為,好的工程師是會寫文件的,SA/SD要很會寫,軟體架構師更是要超會寫,但要寫得有組織架構,條理分明,面面俱到的文件,卻是不容易的,在此將個人的寫文件經驗分享出來。
在這邊不用去爭論什麼文件無用論,無用是因為你不會用,你說文件內容與實際執行不準確,那是因為:
1.組織中沒有技術主編,或是專門人員在review文件內容。
2.沒有文件管理流程,導致文件與現實差距過大。
但我還是建議要學會寫文件的技巧,寫文件的過程本身就是一種設計或是review的過程。
你更要學的是:如何避免寫出沒有用的文件。
開始前的準備:
工具:這是一致性的問題。
選擇.doc或是.html;繪圖工具使用Visio還是Word/PowerPoint;UML使用Enterprise Architecture還是StarUML;單獨用或是混和用?
除了文件格式是一開始就要決定的,其他的越早決定越好。
排版:Word樣式/ CSS
這真的很重要,使用.doc的話,請一開始就提供 dot的範本檔,其中標題一、二、三、四的字體大小、格式、顏色都是一開始就要訂的,寫程式的通常還要來個程式碼的樣式,像下面的範例:
頁首頁尾、圖/表書寫格式也通通不能少,請認真地去看侯大師的word排版藝術,若是你是一個架構師,請注意,你必然少不掉要review很多文件,賞心悅目的排版會讓你比較好review下去。
CSS 當然也是比照辦理。
繪圖:圖的格式 / 顏色
這個很難,你很難教導大家的圖解都是乾淨俐落,言之有物的,所謂的意圖這件事,我稍後會講到。
不過最基本的格式、顏色總是要規範的,我最常遇到的就是,這張圖示中的黃色是表示A系統,但同一層級的B系統卻是使用綠色之類的,這樣會讓人混淆的,顏色也不要使用太多,像下圖所示:
注意到圖中下面的一個重點就是,你有將使用的顏色代表的涵義說明出來;當然若是使用不同的圖形(圓形/三角形),也請記得做圖示說明。
另外很多類似的表示圖示,也需統一用的時機,像表示人的圖像可能有下列幾種:
但不要一張圖出現好幾種人示,可以用文字或顏色分辨即可。
為求統一,也必須說明什麼圖形什麼顏色是表示什麼。
當然,習慣法 / 專用語也是必然要一致的,有機會我們在說明SA時會在Glossary章節再講。
文件版本控制:這是一個大問題,文件交換通常都是copy來copy去的,結果大家在溝通時,常常牛頭不對馬嘴,因為看到的是不同的版本;當然我們可以使用CVS、SVN之類的版本控管,或是KM、目錄分享的方式,做到”盡量”大家拿到的都是同一版本的文件,可是merge時又是一個大問題。
但要秉持一個原則:文件的reference只有一個。
也就是大家都說好,不管怎麼copy,反正就是以那個位置的文件為主要參考。未更新則是個人的責任。
像我們使用Google docs來處理這個問題,永遠只有一份參考,也只共同編輯這一份。
建議要有一個技術主編(同常也是架構師啦),可以由主編指派個人寫的每一小章節,再予以統合,這樣才能保證文件的一致性以及品質。
繪圖
技術文件中,畫圖是一件困難的事,因為,我們從未被好好地教導過如何畫圖這件事。
也因此,一張圖當中常常顯示了太多的訊息,這樣導致看圖的人不見得能清楚地接收你在圖中想傳達的訊息。
一圖勝千言。
沒經驗的人通常就是想到什麼畫什麼,一張圖塞得滿滿的,好像全部都說到了,就自以為交待清楚了。
那看圖的人就很可憐了,全部都在一張圖裡面找線索;這也不是說不行,反正最後大家都有得到所要的資訊就是了,只是溝通成本會增加很多。
這跟藝術上構圖是相同的,盡可能讓一張圖只有 1~2個要凸顯的目的。
要記得,說太多等於沒說。
所以第一件要做的就是:分類。
不同的訊息放在不同的圖。
搞過房子裝潢的就知道,通常除了隔間的圖外,還有插座配置、燈具配置、水管口……好幾張圖,都是分開畫,給不同的師傅看的時候用。
之後我們會提到,這就是”View”的用法。
注意,我們需要從不同的視野來看同一件事,不同的圖給不同的相關者看。
接這就是分層。
原則就是由大而小。
相同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 意見:
我想知道那些圖是哪個工具的, 滿漂亮的
呵呵 , 使用ConceptDraw Office畫的~
好文章!謝謝您!
張貼留言