論軟件項(xiàng)目需求文檔的撰寫

論軟件項(xiàng)目需求文檔的撰寫

1引言大多數(shù)工程師在撰寫需求文檔的時(shí)候，主要考慮的是如何把邏輯講清楚。這實(shí)際上是從自身出發(fā)的一種思維模式。所謂的講清楚，是自己認(rèn)為講清楚了，因?yàn)樽约罕旧硪呀?jīng)有一定的認(rèn)識(shí)，所以只要寫下來的是對的，那都屬于講清楚了的范疇。但自己認(rèn)為得講清楚未必等于讀者的講清楚了，讀者由于原來對該事物沒有認(rèn)識(shí)，或者雖有認(rèn)識(shí)但有些偏差，因而，當(dāng)讀者通過文檔收獲的東西不完全等于寫者想表達(dá)的所有內(nèi)容時(shí)，就不能定義為講清楚了。筆者建議，在撰寫需求文檔時(shí)，要用目標(biāo)讀者的角度去衡量怎樣把事情交代清楚，怎樣能夠讓目標(biāo)讀者方便閱讀、方便理解。做到心中有讀者，就能使得軟件項(xiàng)目需求文檔的質(zhì)量不斷有提高。2需求文檔的涵蓋范圍一般情況下，需求文檔用需求模型和以用例為主體的文檔相結(jié)合來表現(xiàn)。模型可以給讀者以清晰、明確地主觀印象。但因?yàn)槠涑橄笮裕荒馨阉行畔⒈磉_(dá)出來，更需要以文字解說的方式來補(bǔ)充。當(dāng)一堆信息豐富的文字不分輕重緩急放在一起呈現(xiàn)給讀者的時(shí)候，讀者體會(huì)到的是雜亂，需要花很多心思去理清關(guān)系。用例在這時(shí)就應(yīng)運(yùn)而生，它能夠幫助編寫者很好地組織信息，也可能幫助閱讀者快速找到需要的信息。用例是需求，如果編寫恰當(dāng)，用例可以準(zhǔn)確地對系統(tǒng)必須要做什么進(jìn)行詳細(xì)地描述。但另一方面，用例不是所有的需求，用例部詳細(xì)地描述外部接口、數(shù)據(jù)格式、業(yè)務(wù)規(guī)則和復(fù)雜的公式。用例只是需要收集的所有需求中的一部分，雖然這一部分非常重要，但畢竟僅僅是一部分。業(yè)務(wù)規(guī)則、詞匯表、性能目標(biāo)、過程需求和許多其他方面的東西都不屬于行為需求之列，因此不屬于用例的范疇[1]。本文的需求文檔是一個(gè)泛指，泛指所有和需求有關(guān)的文檔，包括用例、業(yè)務(wù)規(guī)則、詞匯表等等。3需求文檔的兩難境地筆者在一家公司的軟件部門工作7年有余，參加過5個(gè)以上不同的軟件項(xiàng)目組，更觀察了超過10個(gè)以上公司內(nèi)外軟件團(tuán)隊(duì)的工作。目前軟件團(tuán)隊(duì)中需求文檔的讀者主要是用戶、客戶;系統(tǒng)分析員、需求分析員;軟件開發(fā)者、程序員;測試員;項(xiàng)目管理者等。方方面面的人員對于需求文檔的不同要求，加上需求工程師們對自己撰寫的文檔的一些認(rèn)識(shí)和要求造成了需求文檔的一些兩難境地，通過一些現(xiàn)象表現(xiàn)出來。現(xiàn)象一：用戶代表們看完所有的厚厚一疊需求文檔(主要是用例)后，覺得很茫然，好像文檔所敘述的內(nèi)容都沒有問題，但對根據(jù)文檔開發(fā)出來的軟件是否是自己需要的并沒有把握。現(xiàn)象二：開發(fā)工程師和質(zhì)量工程師們總是反映需求文檔不夠細(xì)致，不能體現(xiàn)到每個(gè)按鈕、每個(gè)字段的要求。對開發(fā)和測試工程師們來說這些信息確實(shí)屬于需求的一部分，而對于需求工程師們來說，這樣的文檔撰寫、維護(hù)所耗費(fèi)的精力實(shí)在是無可估量的。在一些沒有專職的系統(tǒng)設(shè)計(jì)師的團(tuán)隊(duì)中，需求工程師要拿捏尺度，在需求文檔和設(shè)計(jì)文檔中尋找平衡點(diǎn)，也不是一件容易的事。現(xiàn)象三：在開發(fā)團(tuán)隊(duì)中做熟的一些工程師們，希望每個(gè)迭代的文檔更有針對性。如果每個(gè)迭代的需求文檔都是在之前的需求文檔上的疊加，那么他們往往要花費(fèi)很多時(shí)間和精力去把那些修改之處找出來。然而，當(dāng)需求工程師們，順應(yīng)大家的要求，按迭代周期撰寫需求文檔時(shí)，新近加入的工程師們又抱怨連連：他們沒有辦法，看到系統(tǒng)到當(dāng)下最正確且及時(shí)的情況以文檔來反映，當(dāng)他們從0.1，0.2版本的文檔閱讀到0.5，1.0時(shí)，赫然發(fā)現(xiàn)之前所閱讀并記憶的很多東西其實(shí)已經(jīng)完全被摒棄或者有了天翻地覆的變化。當(dāng)然，也有可能當(dāng)他們讀到1.0版本時(shí)，已經(jīng)不記得0.2版本寫了什么了?，F(xiàn)象四：需求工程師們把需求文檔看成是一個(gè)累贅，對他們來說分析清楚需求，是一件很有挑戰(zhàn)的工作。然而，撰寫需求文檔，只是一個(gè)很枯燥的工作，看上去全然沒有創(chuàng)造性，反而吃力不討好——沒有最好的文檔，總有人有不滿意見。在撰寫新文檔上，需求工程師們可能受到流程控制、實(shí)際需要而忙碌工作于文檔上，但對于一些需求變更，或者對于需求文檔中二義性詞句的修改，就顯得不那么按部就班。由于工業(yè)化的軟件開發(fā)有很多進(jìn)度的要求，造成文檔評審的效果和結(jié)果都有些折扣，如此一來，需求文檔更成為一種雞肋，食之無味棄之可惜。其實(shí)，對于需求文檔，方方面面的意見實(shí)在太多太雜，舉不勝數(shù)。然而，需求工程師們就真的在需求文檔行這道坎前束手無策，坐以待斃么?答案當(dāng)然是否定的。把需求文檔的撰寫看作是需求工作中的重要一環(huán)，把需求文檔的質(zhì)量看作是自身業(yè)務(wù)水平的一個(gè)體現(xiàn)，需求文檔一定能有起到其在軟件開發(fā)中的應(yīng)有作用。4高質(zhì)量需求文檔的衡量標(biāo)準(zhǔn)需求是一種知識(shí)，知識(shí)在被轉(zhuǎn)播的過程中需要一種用載體來呈現(xiàn)，需求文檔正是這樣一種載體。如果需求本身在獲取的過程中已經(jīng)出現(xiàn)質(zhì)量問題，那么需求文檔質(zhì)量再高也只能反映有缺陷的需求;反之，如果編撰需求文檔的能力非常低下，那么高質(zhì)量的需求在別人眼中就成為殘缺不齊的需求。因此需求文檔的質(zhì)量要求和需求本身的質(zhì)量要求實(shí)際上是一致的。兩者密不可分。對于需求和需求文檔，目前普遍的認(rèn)識(shí)是要具有以下特性，或稱之為高下的衡量標(biāo)準(zhǔn)[2]。1)完整性：不能遺漏任何必要的需求信息，需求本身是要完整的，而需求文檔也要完整地表述需求。2)一致性：需求之間要不相矛盾，在文檔的字里行間也要保持一致。3)可修改性：需求會(huì)因?yàn)楦鞣N原因而發(fā)生變化，這是無可奈何的現(xiàn)實(shí)，需求文檔總是體現(xiàn)需求，因此需求文檔必須是可以被修改的。4)可跟蹤性：應(yīng)能在每項(xiàng)軟件需求與它的根源和設(shè)計(jì)元素、源代碼、測試用例之間建立起鏈接鏈，5)作為文檔，可閱讀性、可維護(hù)性、無二義性也都很重要。6)可閱讀性：一般說來，第一眼看去版面規(guī)整、長度適當(dāng)?shù)奈臋n是讀者愿意閱讀的。再看內(nèi)容條理清楚、層次分明、能容易抓住重點(diǎn)的文檔是讀者在初讀之后還愿意繼續(xù)往下讀的關(guān)鍵。7)可維護(hù)性：相同的內(nèi)容如果無數(shù)次的出現(xiàn)并散落在文檔各處無疑會(huì)給文檔的長期更新帶來隱患，可維護(hù)性反映在維護(hù)文檔的人能夠很容易的知道應(yīng)該更新文檔的哪些地方并且如何根據(jù)實(shí)際需要去更新。8)無二義性：文字的魅力在于豐富多樣，而文字的挑戰(zhàn)同樣在這里，如何讓讀的人接收到寫的人想要交代的信息，不多不少剛剛好，是一個(gè)很大的難題。5“想著讀者”撰寫需求文檔的建議建議一：每個(gè)文檔或每段文字都要有明確的目標(biāo)讀者為了減少維護(hù)文檔的工作量，有些需求工程師喜歡用一個(gè)文檔記錄所有需求相關(guān)的信息。這當(dāng)然不是不可以，但上文提到，需求文檔的讀者其實(shí)很多，用戶、客戶、系統(tǒng)分析員、需求工程師、開發(fā)工程師、質(zhì)量工程師、項(xiàng)目經(jīng)理等[3]。事實(shí)上，每個(gè)角色看文檔的目的是不一樣的，因此他們各自對文檔的要求也是不一樣的。從“為讀者著想”的指導(dǎo)思想出發(fā)，高質(zhì)量的需求文檔，需要讓讀者一眼就能明白哪些是他關(guān)心的內(nèi)容，他需要詳細(xì)閱讀，哪些是寫給其他角色看的，他可以跳過不看，而不是等他讀完了才發(fā)現(xiàn)這些信息和他無關(guān)。也就是說，即使只有一個(gè)需求文檔，在文檔中間也應(yīng)該很用明確的標(biāo)識(shí)來標(biāo)記目標(biāo)讀者是誰。當(dāng)然，如果有些目標(biāo)讀者關(guān)心的內(nèi)容有很大的不同，那么完全沒有必要硬把所有內(nèi)容放在一個(gè)文檔里。因?yàn)槟菢訒?huì)造成文檔的冗長，極其容易讓讀者沒有耐心去看。建議二：利用模板，但不要被模板束縛無論是RUP，IEEE還是Vorath，都提供了軟件開發(fā)文檔的模板，其中就包括需求相關(guān)的文檔模板。模板是可以也應(yīng)該根據(jù)項(xiàng)目和企業(yè)的實(shí)際情況進(jìn)行裁減的，這是業(yè)界普遍認(rèn)同的。但是隨意翻閱一些軟件項(xiàng)目的需求文檔，尤其是通過了CMM/CMMILevel3或更高級評定的軟件項(xiàng)目，不難發(fā)現(xiàn)，文檔中很多方面的內(nèi)容流于形式。例如用例目的(Objective)大多都是“通過這個(gè)用例用戶可以****”，****就是用例名或其近義詞，又如，在系統(tǒng)響應(yīng)速度的要求中，大多數(shù)都是“3秒內(nèi)”或“平均3秒，最壞情況5秒”。這樣的需求文檔實(shí)際上是沒有質(zhì)量的。二出現(xiàn)這種情況的主要原因就是需求工程師覺得沒什么可寫，但又必須填一些內(nèi)容。事實(shí)上，在撰寫需求文檔時(shí)，發(fā)現(xiàn)任何一個(gè)段落(Section)的內(nèi)容經(jīng)常不知道怎么填，而隨手寫一句話或幾個(gè)詞的時(shí)候，就應(yīng)該把問題拿出來分析。探討一下這個(gè)段落是不是真的有用，那個(gè)角色會(huì)關(guān)心這個(gè)段落，是不是可以不要這個(gè)段落，如果還是有保留意義的話，那應(yīng)該怎樣寫才能起到該段落的作用。如討論對系統(tǒng)響應(yīng)速度的要求，需求工程師們就會(huì)發(fā)現(xiàn)，在商業(yè)系統(tǒng)中，數(shù)據(jù)量對系統(tǒng)的響應(yīng)速度影響很大，因此，寬泛的說3秒完成一個(gè)動(dòng)作是不合適的。相反，需求工程師應(yīng)該詳細(xì)給出諸如“70%的集裝箱裝載的貨物在100種以內(nèi)，要求3秒內(nèi)用戶可以在系統(tǒng)界面上看到集裝箱內(nèi)的全部貨物信息，100-200種貨物的集裝箱信息要求在5秒以內(nèi)顯示，若貨物條目超過200條的情況系統(tǒng)可以不考慮?！苯ㄗh三：多些業(yè)務(wù)信息、假設(shè)(Assumption)描述事物的方法無外乎兩種方法，一種是描述對的情況，把對的信息一條條疊加，就能看到對的事物的全貌。第二種是描述排外情況，把世界比作一個(gè)大空間，那些排除出去的以外就是人們需要的事物了。大部分情況下，需求文檔都用第一種方法來描述需求，即需求是什么。然而，世界太大，每一件事物可以從許許多多不同的角度來描述。而需求文檔是有限的，人的思維也有一些定式。因而需求文檔一定做不到完美——無一遺漏、一網(wǎng)打盡。這時(shí)候，建議用兩種方法結(jié)合的方式，來對需求進(jìn)行描述，就會(huì)更好。假設(shè)信息實(shí)際上有很重要的作用。根據(jù)投資回報(bào)率理論，系統(tǒng)目標(biāo)解決80%的業(yè)務(wù)，而不是100%，因此遇到一些特殊情況，很有可能在需求討論的時(shí)候已經(jīng)有決策，即不需要系統(tǒng)處理這些情況。其實(shí)這些排外情況也是需求的一部分。應(yīng)該要在需求文檔中得到體現(xiàn)。筆者接觸的很多項(xiàng)目都忽視了這點(diǎn)，因而造成日后在系統(tǒng)運(yùn)行過程中用戶和開發(fā)團(tuán)隊(duì)產(chǎn)生分歧，用戶覺得是系統(tǒng)缺陷，而開發(fā)團(tuán)隊(duì)覺得需求就是如此，但苦于沒有文檔作證。前文的例子中，“70%的集裝箱裝載的貨物在100種以內(nèi)”就是對“對的”需求的描述，而“若貨物條目超過200條的情況系統(tǒng)可以不考慮”就是一種排外情況。兩者結(jié)合起來，才能讓開發(fā)工程師和質(zhì)量工程師知道應(yīng)該怎么進(jìn)行。多描述業(yè)務(wù)還有幾個(gè)好處[4]，其一，業(yè)務(wù)其實(shí)很少改變或者說改變得很慢，但系統(tǒng)是很容易就需要改變的，多描述業(yè)務(wù)實(shí)際上可以降低文檔的維護(hù)工作量。其二，尤其對于商業(yè)應(yīng)用系統(tǒng)，如果能夠盡可能的讓開發(fā)工程師和質(zhì)量工程師明白業(yè)務(wù)是怎么回事，那么開發(fā)工程師可以從需求中看到業(yè)務(wù)，在進(jìn)行設(shè)計(jì)、編碼的時(shí)候，為業(yè)務(wù)長遠(yuǎn)的發(fā)展預(yù)留空間，而質(zhì)量工程師可以更多地設(shè)計(jì)符合80%業(yè)務(wù)的測試用例，而不僅僅按照測試?yán)碚搧碓O(shè)計(jì)測試用例，那么這樣的測試能夠更有針對性和效率。建議四：規(guī)范用詞，提供適當(dāng)?shù)拈喿x指南大部分關(guān)于用例模板、需求規(guī)約模板中都有“詞匯表”這個(gè)部分，的確這是一個(gè)規(guī)范用詞的做法，詞匯表實(shí)際上也是對一些專有名詞進(jìn)行注解，以方便讀者理解。然而，用詞的規(guī)范，應(yīng)該不僅僅只是專用名詞、術(shù)語，更可以推廣到動(dòng)詞和句式。需求文檔作為技術(shù)文檔的一種，和普通文藝作品截然不同。文藝作品講究重復(fù)強(qiáng)調(diào)主題，但又需要用很多不同的近義詞來凸顯主題。而作為技術(shù)文檔，同義詞只會(huì)引起一些敏感的開發(fā)、測試人員的疑惑。例如“編輯Edit”、“更改Modify”、“修改Amend”、“維護(hù)Maintain”究竟在文檔中表明一個(gè)意思還是各有不同，的確是一個(gè)值得揣摩的問題。需求撰寫人的隨意用詞會(huì)給認(rèn)真的讀者帶來很多遐想空間，這在文藝作品來說可能是一種效果，然而技術(shù)文檔不需要。如果需求文檔撰寫人對這些近義詞的用法能夠有一個(gè)說明，并且在所有文檔中保證用法一致，那么無疑會(huì)受到讀者的好評。因?yàn)檫@樣一致的做法可以確保無二義性的產(chǎn)生。需求文檔在句式上也可以用一些方法來規(guī)整[5]。比如，表示用戶想要開始進(jìn)行某項(xiàng)操作時(shí)，不寫成“用戶進(jìn)入**菜單”，而寫成“用戶想要進(jìn)行**操作/工作”。那么，當(dāng)一份文檔里第三次出現(xiàn)這個(gè)句式時(shí)讀者就能直奔主題，直接閱讀中間是什么核心內(nèi)容，而不再需要閱讀前后的輔詞。其實(shí)，這樣做同樣能給需求文檔撰寫人帶來好處也是很明顯的。在撰寫需求文檔的時(shí)候，一個(gè)詞可以表達(dá)一種確切的含義，甚至可以超出詞語的本意，而不需要每次洋洋灑灑重復(fù)介紹;同樣的句式可以把重點(diǎn)放在主題上，讓工作更有效率，在以后的維護(hù)中，也可以用工具幫助查找同樣的詞或句式，保證沒有遺漏。建議五：善用各種工具進(jìn)行版本管理由于需求文檔的可修改特性，文檔的版本管理也是相當(dāng)重要的。專門用于文檔管理的工具有VSS，Sharepoint等，但是沒有這些專業(yè)工具并不表示就不能進(jìn)行文檔的版本管理了。MicrosoftWord加上合理創(chuàng)建文件夾結(jié)構(gòu)就可以很好地解決文檔版本管理的難題。對于文檔版本的管理，有兩個(gè)主要目標(biāo)，一是總能找到最近的一個(gè)版本，也就是最后更新的，這個(gè)文檔能夠給任何團(tuán)隊(duì)外的咨詢者或者團(tuán)隊(duì)中的新成員以足夠的信息，所謂最后更新，即能夠在沒有任何修改或情況說明的情況下，提供文檔讓需要者去閱讀，而不會(huì)因?yàn)槟承┬枰咛岢鲆蟛湃バ薷母挛臋n。二是能夠快速定位某年某月的某個(gè)版本究竟有哪些改動(dòng)，改動(dòng)之前是怎樣的，改動(dòng)之后又是怎樣的。如果哪個(gè)版本恰巧和軟件產(chǎn)品的一個(gè)發(fā)布版本吻合，那么開發(fā)工程師和質(zhì)量工程師們實(shí)際上只要關(guān)注那些改動(dòng)的部分就足夠了。換言之，達(dá)到以上兩個(gè)目標(biāo)就很好地解決了現(xiàn)象三種的兩難境地。善加使用MicrosoftWord中的Track功能是一個(gè)很好的建議。當(dāng)決定文檔需要保留一個(gè)版本的時(shí)候，就應(yīng)該把當(dāng)前的文檔另存，并修改文件名，增加版本信息，例如“需求規(guī)約v2.3.doc”。而主文件名保持沒有版本信息的狀況“需求規(guī)約.doc”。當(dāng)開始新一個(gè)版本周期v2.4工作的時(shí)候，第一件