心中有讀者——論軟件項目需求文檔的撰寫

摘要：在軟件項目走上工業化流程的今天，軟件工程中需求工程已經越來越受到重視。而需求工程中需求文檔的撰寫，一直是做好需求工作的重要一環。本文通過對當前軟件項目團隊中集中體現的用戶、開發工程師、質量工程師等對需求文檔的不滿，結合需求工程師自身在撰寫和維護文檔上工作量的考量，提出在編撰軟件項目需求文檔時應該始終懷揣著讀者的需要，從而更好地編撰可讀性高、高度清晰完整、可維護性也高的需求文檔，使得軟件產品的質量能從第一道工序開始得到保證。

關鍵詞：軟件工業；需求文檔；高質量

中圖分類號：TP311.5 文獻標識碼：A 文章編號：1009-3044(2009)05-1118-03

With Readers in Mind

XUE Bei-yan

(School of Software， Shanghai Jiaotong University， Shanghai， 200030， China;)

Abstract： Nowadays， developing software has already became and software industry. Requirement Engineering is becoming more and more important in the overall software engineering. Among which， requirement document composing is a very significant task. Through the complaint on the requirement documentations from customer， development engineers， quality assurance engineers， etc， and considering the workload of the requirement engineers on document preparation and maintenance as well， this article points out that with readers in mind all the times can help to deliver a high quality requirement document with high readability and maintainability clearly and completely， so that the quality of software product can be ensure from every beginning.

Key words: software industry; requirement documentation; high quality

1 引言

大多數工程師在撰寫需求文檔的時候，主要考慮的是如何把邏輯講清楚。這實際上是從自身出發的一種思維模式。所謂的講清楚，是自己認為講清楚了，因為自己本身已經有一定的認識，所以只要寫下來的是對的，那都屬于講清楚了的范疇。但自己認為得講清楚未必等于讀者的講清楚了，讀者由于原來對該事物沒有認識，或者雖有認識但有些偏差，因而，當讀者通過文檔收獲的東西不完全等于寫者想表達的所有內容時，就不能定義為講清楚了。筆者建議，在撰寫需求文檔時，要用目標讀者的角度去衡量怎樣把事情交代清楚，怎樣能夠讓目標讀者方便閱讀、方便理解。做到心中有讀者，就能使得軟件項目需求文檔的質量不斷有提高。

2 需求文檔的涵蓋范圍

一般情況下，需求文檔用需求模型和以用例為主體的文檔相結合來表現。模型可以給讀者以清晰、明確地主觀印象。但因為其抽象性，不能把所有信息表達出來，更需要以文字解說的方式來補充。當一堆信息豐富的文字不分輕重緩急放在一起呈現給讀者的時候，讀者體會到的是雜亂，需要花很多心思去理清關系。用例在這時就應運而生，它能夠幫助編寫者很好地組織信息，也可能幫助閱讀者快速找到需要的信息。

用例是需求，如果編寫恰當，用例可以準確地對系統必須要做什么進行詳細地描述。但另一方面，用例不是所有的需求，用例部詳細地描述外部接口、數據格式、業務規則和復雜的公式。用例只是需要收集的所有需求中的一部分，雖然這一部分非常重要，但畢竟僅僅是一部分。業務規則、詞匯表、性能目標、過程需求和許多其他方面的東西都不屬于行為需求之列，因此不屬于用例的范疇[1]。本文的需求文檔是一個泛指，泛指所有和需求有關的文檔，包括用例、業務規則、詞匯表等等。

3 需求文檔的兩難境地

筆者在一家公司的軟件部門工作7年有余，參加過5個以上不同的軟件項目組，更觀察了超過10個以上公司內外軟件團隊的工作。目前軟件團隊中需求文檔的讀者主要是用戶、客戶；系統分析員、需求分析員；軟件開發者、程序員；測試員；項目管理者等。方方面面的人員對于需求文檔的不同要求，加上需求工程師們對自己撰寫的文檔的一些認識和要求造成了需求文檔的一些兩難境地，通過一些現象表現出來。

現象一：用戶代表們看完所有的厚厚一疊需求文檔（主要是用例）后，覺得很茫然，好像文檔所敘述的內容都沒有問題，但對根據文檔開發出來的軟件是否是自己需要的并沒有把握。

現象二：開發工程師和質量工程師們總是反映需求文檔不夠細致，不能體現到每個按鈕、每個字段的要求。對開發和測試工程師們來說這些信息確實屬于需求的一部分，而對于需求工程師們來說，這樣的文檔撰寫、維護所耗費的精力實在是無可估量的。在一些沒有專職的系統設計師的團隊中，需求工程師要拿捏尺度，在需求文檔和設計文檔中尋找平衡點，也不是一件容易的事。

現象三：在開發團隊中做熟的一些工程師們，希望每個迭代的文檔更有針對性。如果每個迭代的需求文檔都是在之前的需求文檔上的疊加，那么他們往往要花費很多時間和精力去把那些修改之處找出來。然而，當需求工程師們，順應大家的要求，按迭代周期撰寫需求文檔時，新近加入的工程師們又抱怨連連：他們沒有辦法，看到系統到當下最正確且及時的情況以文檔來反映，當他們從0.1，0.2版本的文檔閱讀到0.5，1.0時，赫然發現之前所閱讀并記憶的很多東西其實已經完全被摒棄或者有了天翻地覆的變化。當然，也有可能當他們讀到1.0版本時，已經不記得0.2版本寫了什么了。

現象四：需求工程師們把需求文檔看成是一個累贅，對他們來說分析清楚需求，是一件很有挑戰的工作。然而，撰寫需求文檔，只是一個很枯燥的工作，看上去全然沒有創造性，反而吃力不討好——沒有最好的文檔，總有人有不滿意見。在撰寫新文檔上，需求工程師們可能受到流程控制、實際需要而忙碌工作于文檔上，但對于一些需求變更，或者對于需求文檔中二義性詞句的修改，就顯得不那么按部就班。由于工業化的軟件開發有很多進度的要求，造成文檔評審的效果和結果都有些折扣，如此一來，需求文檔更成為一種雞肋，食之無味棄之可惜。

其實，對于需求文檔，方方面面的意見實在太多太雜，舉不勝數。然而，需求工程師們就真的在需求文檔行這道坎前束手無策，坐以待斃么？答案當然是否定的。把需求文檔的撰寫看作是需求工作中的重要一環，把需求文檔的質量看作是自身業務水平的一個體現，需求文檔一定能有起到其在軟件開發中的應有作用。

4 高質量需求文檔的衡量標準

需求是一種知識，知識在被轉播的過程中需要一種用載體來呈現，需求文檔正是這樣一種載體。如果需求本身在獲取的過程中已經出現質量問題，那么需求文檔質量再高也只能反映有缺陷的需求；反之，如果編撰需求文檔的能力非常低下，那么高質量的需求在別人眼中就成為殘缺不齊的需求。因此需求文檔的質量要求和需求本身的質量要求實際上是一致的。兩者密不可分。

對于需求和需求文檔，目前普遍的認識是要具有以下特性，或稱之為高下的衡量標準[2]。

1) 完整性：不能遺漏任何必要的需求信息，需求本身是要完整的，而需求文檔也要完整地表述需求。

2) 一致性：需求之間要不相矛盾，在文檔的字里行間也要保持一致。

3) 可修改性：需求會因為各種原因而發生變化，這是無可奈何的現實，需求文檔總是體現需求，因此需求文檔必須是可以被修改的。

4) 可跟蹤性：應能在每項軟件需求與它的根源和設計元素、源代碼、測試用例之間建立起鏈接鏈，

5) 作為文檔，可閱讀性、可維護性、無二義性也都很重要。

6) 可閱讀性：一般說來，第一眼看去版面規整、長度適當的文檔是讀者愿意閱讀的。再看內容條理清楚、層次分明、能容易抓住重點的文檔是讀者在初讀之后還愿意繼續往下讀的關鍵。

7) 可維護性：相同的內容如果無數次的出現并散落在文檔各處無疑會給文檔的長期更新帶來隱患，可維護性反映在維護文檔的人能夠很容易的知道應該更新文檔的哪些地方并且如何根據實際需要去更新。

8) 無二義性：文字的魅力在于豐富多樣，而文字的挑戰同樣在這里，如何讓讀的人接收到寫的人想要交代的信息，不多不少剛剛好，是一個很大的難題。

5 “想著讀者”撰寫需求文檔的建議

建議一：每個文檔或每段文字都要有明確的目標讀者

為了減少維護文檔的工作量，有些需求工程師喜歡用一個文檔記錄所有需求相關的信息。這當然不是不可以，但上文提到，需求文檔的讀者其實很多，用戶、客戶、系統分析員、需求工程師、開發工程師、質量工程師、項目經理等[3]。事實上，每個角色看文檔的目的是不一樣的，因此他們各自對文檔的要求也是不一樣的。從“為讀者著想”的指導思想出發，高質量的需求文檔，需要讓讀者一眼就能明白哪些是他關心的內容，他需要詳細閱讀，哪些是寫給其他角色看的，他可以跳過不看，而不是等他讀完了才發現這些信息和他無關。也就是說，即使只有一個需求文檔，在文檔中間也應該很用明確的標識來標記目標讀者是誰。

當然，如果有些目標讀者關心的內容有很大的不同，那么完全沒有必要硬把所有內容放在一個文檔里。因為那樣會造成文檔的冗長，極其容易讓讀者沒有耐心去看。

建議二：利用模板，但不要被模板束縛

無論是RUP，IEEE還是Vorath，都提供了軟件開發文檔的模板，其中就包括需求相關的文檔模板。模板是可以也應該根據項目和企業的實際情況進行裁減的，這是業界普遍認同的。但是隨意翻閱一些軟件項目的需求文檔，尤其是通過了CMM/CMMI Level 3或更高級評定的軟件項目，不難發現，文檔中很多方面的內容流于形式。例如用例目的（Objective）大多都是“通過這個用例用戶可以****”，****就是用例名或其近義詞，又如，在系統響應速度的要求中，大多數都是“3秒內”或“平均3秒，最壞情況5秒”。這樣的需求文檔實際上是沒有質量的。二出現這種情況的主要原因就是需求工程師覺得沒什么可寫，但又必須填一些內容。

事實上，在撰寫需求文檔時，發現任何一個段落（Section）的內容經常不知道怎么填，而隨手寫一句話或幾個詞的時候，就應該把問題拿出來分析。探討一下這個段落是不是真的有用，那個角色會關心這個段落，是不是可以不要這個段落，如果還是有保留意義的話，那應該怎樣寫才能起到該段落的作用。如討論對系統響應速度的要求，需求工程師們就會發現，在商業系統中，數據量對系統的響應速度影響很大，因此，寬泛的說3秒完成一個動作是不合適的。相反，需求工程師應該詳細給出諸如“70%的集裝箱裝載的貨物在100種以內，要求3秒內用戶可以在系統界面上看到集裝箱內的全部貨物信息，100-200種貨物的集裝箱信息要求在5秒以內顯示，若貨物條目超過200條的情況系統可以不考慮。”

建議三：多些業務信息、假設（Assumption）

描述事物的方法無外乎兩種方法，一種是描述對的情況，把對的信息一條條疊加，就能看到對的事物的全貌。第二種是描述排外情況，把世界比作一個大空間，那些排除出去的以外就是人們需要的事物了。大部分情況下，需求文檔都用第一種方法來描述需求，即需求是什么。然而，世界太大，每一件事物可以從許許多多不同的角度來描述。而需求文檔是有限的，人的思維也有一些定式。因而需求文檔一定做不到完美——無一遺漏、一網打盡。這時候，建議用兩種方法結合的方式，來對需求進行描述，就會更好。

假設信息實際上有很重要的作用。根據投資回報率理論，系統目標解決80%的業務，而不是100%，因此遇到一些特殊情況，很有可能在需求討論的時候已經有決策，即不需要系統處理這些情況。其實這些排外情況也是需求的一部分。應該要在需求文檔中得到體現。筆者接觸的很多項目都忽視了這點，因而造成日后在系統運行過程中用戶和開發團隊產生分歧，用戶覺得是系統缺陷，而開發團隊覺得需求就是如此，但苦于沒有文檔作證。

前文的例子中，“70%的集裝箱裝載的貨物在100種以內”就是對“對的”需求的描述，而“若貨物條目超過200條的情況系統可以不考慮”就是一種排外情況。兩者結合起來，才能讓開發工程師和質量工程師知道應該怎么進行。

多描述業務還有幾個好處[4]，其一，業務其實很少改變或者說改變得很慢，但系統是很容易就需要改變的，多描述業務實際上可以降低文檔的維護工作量。其二，尤其對于商業應用系統，如果能夠盡可能的讓開發工程師和質量工程師明白業務是怎么回事，那么開發工程師可以從需求中看到業務，在進行設計、編碼的時候，為業務長遠的發展預留空間，而質量工程師可以更多地設計符合80%業務的測試用例，而不僅僅按照測試理論來設計測試用例，那么這樣的測試能夠更有針對性和效率。

建議四：規范用詞，提供適當的閱讀指南

大部分關于用例模板、需求規約模板中都有“詞匯表”這個部分，的確這是一個規范用詞的做法，詞匯表實際上也是對一些專有名詞進行注解，以方便讀者理解。然而，用詞的規范，應該不僅僅只是專用名詞、術語，更可以推廣到動詞和句式。

需求文檔作為技術文檔的一種，和普通文藝作品截然不同。文藝作品講究重復強調主題，但又需要用很多不同的近義詞來凸顯主題。而作為技術文檔，同義詞只會引起一些敏感的開發、測試人員的疑惑。例如“編輯Edit”、“更改Modify”、“修改Amend”、“維護Maintain”究竟在文檔中表明一個意思還是各有不同，的確是一個值得揣摩的問題。需求撰寫人的隨意用詞會給認真的讀者帶來很多遐想空間，這在文藝作品來說可能是一種效果，然而技術文檔不需要。如果需求文檔撰寫人對這些近義詞的用法能夠有一個說明，并且在所有文檔中保證用法一致，那么無疑會受到讀者的好評。因為這樣一致的做法可以確保無二義性的產生。

需求文檔在句式上也可以用一些方法來規整[5]。比如，表示用戶想要開始進行某項操作時，不寫成“用戶進入**菜單”，而寫成“用戶想要進行**操作/工作”。那么，當一份文檔里第三次出現這個句式時讀者就能直奔主題，直接閱讀中間是什么核心內容，而不再需要閱讀前后的輔詞。

其實，這樣做同樣能給需求文檔撰寫人帶來好處也是很明顯的。在撰寫需求文檔的時候，一個詞可以表達一種確切的含義，甚至可以超出詞語的本意，而不需要每次洋洋灑灑重復介紹；同樣的句式可以把重點放在主題上，讓工作更有效率，在以后的維護中，也可以用工具幫助查找同樣的詞或句式，保證沒有遺漏。

建議五：善用各種工具進行版本管理

由于需求文檔的可修改特性，文檔的版本管理也是相當重要的。專門用于文檔管理的工具有VSS，Sharepoint等，但是沒有這些專業工具并不表示就不能進行文檔的版本管理了。Microsoft Word加上合理創建文件夾結構就可以很好地解決文檔版本管理的難題。

對于文檔版本的管理，有兩個主要目標，一是總能找到最近的一個版本，也就是最后更新的，這個文檔能夠給任何團隊外的咨詢者或者團隊中的新成員以足夠的信息，所謂最后更新，即能夠在沒有任何修改或情況說明的情況下，提供文檔讓需要者去閱讀，而不會因為某些需要者提出要求才去修改更新文檔。二是能夠快速定位某年某月的某個版本究竟有哪些改動，改動之前是怎樣的，改動之后又是怎樣的。如果哪個版本恰巧和軟件產品的一個發布版本吻合，那么開發工程師和質量工程師們實際上只要關注那些改動的部分就足夠了。換言之，達到以上兩個目標就很好地解決了現象三種的兩難境地。

善加使用Microsoft Word中的Track功能是一個很好的建議。當決定文檔需要保留一個版本的時候，就應該把當前的文檔另存，并修改文件名，增加版本信息，例如“需求規約v2.3.doc”。 而主文件名保持沒有版本信息的狀況“需求規約.doc”。當開始新一個版本周期v2.4工作的時候，第一件要做的事情就是全部接受（Accept All changes in document）上一個版本所做的所有改動，然后再根據實際情況進行文檔修改。如此一來，所有v2.4的更新都會被Word記住，以方便讀者在需要的時候，通過（showing markup）或修改區域（Reviewing Pane）進行快速尋找定位。此外，不建議每個版本周期創建一個文件夾，存放該版本所有文檔的做法。因為有些文檔可能由于該版本沒有被改寫而不會出現在該文件夾中，造成被人忽視，或找不到的情況。建議文檔可以在一個文件夾里全部找到最后更新版本，同樣在這個文件夾下，可以找到被歸檔的以往的版本文件。

6 結束語

近年來，敏捷過程、敏捷文檔是被廣泛提及和研究的論題。然而，敏捷的提出并非打著“敏捷”的幌子逃避文檔的編寫、管理的問題[6]。筆者以為，敏捷，實際上指的是敏捷的撰寫文檔，還要加上敏捷地閱讀文檔。

關于如何提高需求文檔的質量，其實還有很多小建議，例如從文檔排版角度如何提升文檔的可讀性，從文檔結構角度應該要提供一個文檔指引，從文檔管理角度如何使用文檔之間的相互鏈接（文件夾有進行整理、移位的可能）等等。

真正做到心中有讀者，在編撰文檔的時候，應該總是考慮讀者想看什么，怎樣可以快速看文檔，怎樣可提高文檔的有效利用率卻又不過分地夸大一個文檔的作用，諸如此類。能夠用這種服務的心態去編寫需求文檔，一定能編撰出高質量的需求文檔，為整個軟件項目成功做好第一步。

參考文獻：

[1] Cockburn Alistair. Writing Effective Use Case [M]， Addison-Wesley， 2000，15-30.

[2] Wiegers Karl E. Software Requirements [M]， Second Edition， Microsoft Press， 2003， 25-38.

[3] Rüping Andreas.Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects [M]， England: John Wiley Sons， 2003. 24-46 .

[4] Von Halle， Barbara. Business Rules Applied – Building Better Systems Using the Business Rules Approach[M]， New York: John Wiley Sons， 2002， 12-15.

[5] Adolph Steve， Bramble Paul. Patterns for Effective Use Cases[M]， Boston: Addison Wesley， 2001， 6-8.

[6] Robert C. Martin. 鄧輝譯， 敏捷軟件開發：原則、模式與實踐 [M]， 北京: 清華大學出版社 ， 2003.

[7] Gottesdiener Ellen.Requirements by Collaboration: Workshops for Defining Needs [M]， Indianapolis USA: Addison Wesley Professional， 2002.