# 八、輕松寫就功能規格說明書 - 第4節：技巧 好吧，我們已經討論過為什麼要規格，規格裡有什麼，以及誰該寫規格。在這系列的第四篇及最后一篇裡，我要和大家分享一份撰寫良好規格的建議。 在真正有寫規格的團隊中最大的抱怨就是「沒有人在讀」。如果沒有人在讀，寫規格的人通常會變得有點憤世嫉俗。就像以前呆伯特漫畫裡，工程師用一大疊4吋厚的規格書堆起來充當隔間。在典型官僚作風的大公司裡，每個人都花好幾個月寫無聊的規格。等規格寫好就放上書架永遠不再拿下來，然后重頭開始製作產品，完全不管規格裡怎麼寫。這是因為沒人讀規格同時也是因為規格寫得無聊透頂。寫規格的過程應該是個很好的練習，因為它至少能強迫每個人仔細思考問題。不過規格完成后就被束之高閣(沒人看也沒人愛)，會讓大家覺得這只是件毫無價值的工作。 另外如果沒有人讀你的規格，等產品完成推出就會出現很多爭議。某人(管理階層，行銷人員或是客戶)會說：「等一下！你答應過會有蛤蜊蒸鍋的！蛤蜊蒸鍋在哪裡？」然后程式員會說：「不，事實上如果你看看規格第3章第4節的2.3.0.1，就會看到上面明確寫著'沒有蛤蜊蒸鍋。」不過永遠是對的客戶可沒這麼好打發，所以不爽的程式員只好在產品裡加一個蛤蜊蒸鍋(結果讓他們更不相信規格)。另外也可能會有個經理說：「嘿，這個對話框裡的文句都太累贅了，而且每個對話框上方應該都有廣告才對。」然后程式員會垂頭喪氣地說：「可是你批準了規格而且裡面明確的列出每個對話框的配置和內容！」不過經理當然不會真正去讀規格，因為當他想看的時候就開始心不在焉，而更重要的是這和他週二的高爾夫球比賽有衝突。 所以說雖然規格是很好的，不過如果沒人讀就不好了。身為撰寫規格的人，你必須騙大家來讀你的作品，另外也可能要努力不要讓大家過份依賴規格而失去原本已經很差的思考力。 要騙大家來讀你的作品，通常只需改善寫作即可。不過光說句「要當個好作家」就撤手不管實在不太公道。下面列出想讓別人讀規格時絕對要遵守的四個簡易規則。 ## 規則1：要有趣 是的，要騙大家來讀規格的第一個規則就是讓讀規格變得很有趣。別告訴我你生來就沒有幽默感。我才不信呢。每個人隨時都會有好玩的點子，只不過因為覺得會「不專業」所以自我約束。不過有時候你得要打破規則。 如果你讀過我在這個網站寫的一堆垃圾，你會注意裡面到處都有想讓內容更有趣的拙劣企圖。另外往前數第四段我才剛寫了個低級玩笑取笑經理在打高爾夫球。雖然我實際上沒那麼幽默，我還是很努力在嘗試。另外雖說胡扯亂扯試圖表現有趣本身就很滑稽，卻是屬于悲哀的那一型。在寫規格時范例是個表達趣味的好地方。當你需要說個故事解釋某個功能時，千萬不要這樣說： 使用者按Ctrl+N建立一個新的雇員表格，并且開始輸入雇員姓名。 你應該要這樣寫： 豬小姐因為手指太肥按不到單一的鍵，所以拿著一根眼線筆戳鍵盤按出Ctrl+N建出一個新的男友表格。然后輸入單一筆資料"Kermit"。 如果你讀過很多Dave Barry的文章，會發現有個很容易的方法可以逗趣，就是在不需要的地方詳述細節。「愛吵鬧的哈巴狗」就比「狗」有趣。而「豬小姐」也比「使用者」有趣。用「左撇子酪梨農夫」要比「特殊嗜好」好。不要用「不替狗清大便的人應該受罰」，應該說「把他們關在單人囚房，讓他們寂寞到想付錢跟蜘蛛上床。」 附帶一提，如果你認為逗趣不夠專業，那我也沒辦法，只能說你缺乏幽默感。(不要否認。沒有幽默感的人總是不肯承認。你是騙不了我的。)另外如果同事會因為你寫的規格輕鬆有趣很好讀而輕視你的話，就去找別的工作吧，因為生命實在太短暫，不應該把你的白天浪費在這種苛刻悲慘的地方。 ## 規則2：寫規格就像在寫用腦執行的程式 這就是我會認為程式員寫不出好規格的原因。 當你在寫程式時，主要對象是編譯器。沒錯，我知道人也會讀程式，不過通常會讀得很辛苦。對大部份程式員來說，光是要讓程式能正常編譯就夠辛苦了；要把程式寫得容易閱讀簡直是遙不可及。你可以寫： ``` void print_count( FILE* a，char * b，int c ){ fprintf(a，"there are %d %s\n"，c，b);} main(){ int n；n = 10；print_count(stdout，"employees"，n) /* code deliberately obfuscated */ } ``` 或是 ``` printf("there are 10 employees\n"); ``` 輸出是完全一樣的。如果你仔細想想，這就是原因所在，程式員通常都會寫出如下的東西： 假設有個函數AddressOf(x)，作用是由使用者x轉出該使用者的RFC-822格式電子郵件地址，并以ANSI字串輸出。讓我們假設有使用者A和使用者B，A想送電子郵件給使用者B。所以使用者A用其他任意(不是全部)技術建立新訊息，然后在「傳送至：」編輯框內鍵入AddressOf(B)。 這也可以寫成以下的規格： 豬小姐想去吃午飯了，所以打了一封電子郵件并在「傳送至：」框內鍵入Kermit的地址。 技術注解：地址必須是標準的Internet地址(RFC-822格式) 理論上這兩種寫法的「意思」完全一樣，不過除非你很小心的解譯，否則是不可能看懂第一種寫法的。程式員常會嘗試把規格寫得像艱澀的學術論文。他們認為一份「正確」的規格必須在「技術」上完全正確，結果完全攪不清楚狀況。 問題在于規格不光是正確就好，同時還必須是可理解的，以程式設計的術語來說，就是要把規格寫得讓人腦能夠「編譯」。電腦和人腦間最大的差別之一，就是當你定義稍后要用的辭語時電腦會耐心等候。可是對人來說一定要先有動機才會瞭解你在講什麼。人們不會想被迫解譯某些東西，他們只想循序閱讀就能理解。對人來說，你必須先提供整體概念然后才填補細節。而電腦程式則是從頭到尾順序下來全部都是細節。電腦不在意變數名稱是否有意義。而對人腦而言，如果能先講個故事(即使只是片斷也可以)描繪出鮮明的印象，就能夠理解得更清楚。因為我們的腦袋已經演進到能理解故事了。 如果你拿出真實西洋棋賽進行中途的棋局，經驗夠的老手只要一兩秒就能立刻記住每個棋子的位置。不過如果以正常下棋不會走的方法(比如把卒放在第一列或把兩隻黑主教都放在黑格上)移動幾顆棋子，棋手就很難記下棋局。這和電腦思考的方式不同。對能記憶棋局的電腦程式來說，可能及不可能的棋局記起來都一樣。人腦的運作方式并不是隨機存取的；我們腦中的某些路徑會被持續加強，所以某些常見的事物就會比其他東西更易理解。 所以當你在寫規格時得試著想像你的對象是誰，并且想像規格各個部份是要他們瞭解什麼東西。逐句逐句地問自己，就前面已經提供的內容而言，讀到這句話的人能深入理解其涵義嗎？如果對象中有些人不知道RFC-822是什麼，你必須把定義寫出來，或者至少在技術注解中簡述RFC-822，這樣非技術人員才不會一開始就看到一堆專業術語，結果投降永不再看。 ## 規則3：寫得愈簡單愈好 千萬不要覺得簡單句子不夠專業，就使用夸大的正式語句。寫得愈簡單愈好。 人們會認為"use"不夠專業所以改用"utilize"之類的單字。(「不夠專業」這句話又出現了。不管任何時候，只要有人說你不應該如何如何，因為那樣「不夠專業」，你就知道這些人已經沒有真正的理由了。)事實上我認為很多人會覺得寫得清楚明瞭就表示裡面大有文章。 把要講的東西拆成短句。如果你沒辦法把某個句子寫得很清楚，就把它拆成二或三個較短的句子。避免整面的文字牆：也就是說整頁都只有文字。大家遇到這種情況就會嚇到根本不敢看。你什麼時候看過有熱門雜志或報紙裡整頁都是文字的？雜志會從文章裡摘錄引言，然后用超大字體印在頁面正中央，就是為了避免有整頁都是文字的印象。有編號或標上符號的列表，圖片，圖表，表格以及大量空白，都可以讓東西「看起來」更輕鬆。 「雜志會從文章裡摘錄引言，然后用超大字體印在頁面正中央，就是為了避免有整頁都是文字的印象。」 沒有東西比擷取大量的畫面更能增進規格了。正所謂一圖勝千言。撰寫視窗軟體規格的人都應該買一套Visual Basic，然后學到至少能建立模擬畫面。(在麥金塔上就用REAL Basic；寫網頁就用Front Page或Dreamweaver)。然后擷取這些畫面(按Ctrl+PrtSc)再貼進規格內。 ## 規則4：審閱多次并重讀幾遍 嗯，好吧，本來我打算花大量篇幅來闡述這項規則，不過這一項實在是太簡單明顯了。把你的規格審閱多次并重讀幾遍，知道了嗎？當你發現某個句子不是非常容易理解，就把整句重寫一次。 不去解釋規則4省了我很多時間，所以我要額外增加一項規則。 ## 規則5：使用樣板是不好的 要避免製作標準規格樣板的誘惑。最先你可能只是認為，讓「每份規格看起來都一樣」是很重要的。我的建議是這并不重要。這會有什麼差別嗎？你家裡書架上的每本書都長得一模一樣嗎？你希望他們一樣嗎？ 更糟的是如果有了樣板，很容易就會針對各個自認重要的功能在樣板上加上一大堆章節。舉例來說，大比爾下令從今以后，所有Microsquish產品都一定要有個Internet元件。所以現在起規格樣板裡就有一節「Internet元件」。不管是誰在寫也不管內容有多無聊，每個人都得在「Internet元件」那一節填入內容，即使他們只是在寫Microsquish鍵盤的規格。(不然你以為為啥有那麼多無用的Internet購物鍵像雨后春筍般從鍵盤上冒出來。) 等這樣的章節一多，整份樣板就會變得大。(這裡有份非常非常糟糕的規格樣板范例。我的天啊，誰會需要在規格裡放參考書目或一份小辭典呢？)這種巨型樣板的問題就是讓寫規格寫是很可怕的工作，把大家嚇得不敢去寫規格。 規格就是一份你希望大家去讀的文件。就這種觀點來看，規格和紐約客或學校論文沒啥不同。你曾聽說過有哪個教授會拿樣板給學生去寫論文嗎？你曾讀過哪兩篇好文章能套進一份樣板嗎？把這個點子忘了吧