軟件工程文檔規(guī)范(00003)

1、軟件工程文檔規(guī)范-前景文檔摘要本文是軟件工程文檔之一：前景（visio）文檔的寫作規(guī)范， 前景文檔以客戶的語言描述總體的需求說明，它與需求規(guī)格說明書是相互配合的。（2002-10-2209:00:45）By風(fēng)過留楓1. 介紹這一部分應(yīng)該提供整個前景文檔的概述，它包含以下幾部分：1.1前景文檔的目的文檔目的是收集、分析、定義高層用戶需要和產(chǎn)品特征。集中于目標(biāo)用戶所需要的能力以及為什么存在這些需要。有關(guān)系統(tǒng)如何滿足這些需要的特定需求應(yīng)該放在“軟件需求規(guī)格 說明”和“用例規(guī)格說明"中。1.2產(chǎn)品綜述陳述該應(yīng)用系統(tǒng)的目的、版本以及要交付的新特征。這一部分應(yīng)該做以下幾件事：1）確定要創(chuàng)建或增強(qiáng)

2、的產(chǎn)品或應(yīng)用系統(tǒng)；2）提供有關(guān)產(chǎn)品將做什么以及需要時不做什么的一般性描述；3）描述產(chǎn)品的應(yīng)用，包括與相關(guān)的利益、目的、目標(biāo)。1.3參考這一部分應(yīng)該做以下幾件事：1）列出在前景文檔中引用的其他文檔的清單；2）標(biāo)明每個文檔的題目、報(bào)告號（如果有的話）、日期和出版機(jī)構(gòu)；3）指定該參考獲取的來源；4）這個信息可通過引用附錄或其它文檔來提供。2. 用戶描述為了有效地提供滿足客戶需要的產(chǎn)品和服務(wù)， 理解完成這項(xiàng)工作時所面對的挑戰(zhàn)是很有必要的。 這一部分應(yīng)該剖析應(yīng)用系統(tǒng)的用戶和限制用戶生產(chǎn)的關(guān)鍵問題。 這一部分不能用于陳述特定需求，而是提供有關(guān)為什么需要第 5 部分指定的需求的背景和理由。2.1 用戶 /

3、市場統(tǒng)計(jì)歸納總結(jié)激勵產(chǎn)品決策的主要市場統(tǒng)計(jì)； 描述和定位目標(biāo)； 利用潛在用戶數(shù)量或客戶愿意花在試圖滿足你的產(chǎn)品或增強(qiáng)所完成的需要上的錢的數(shù)量來預(yù)測市場的大小和增長率； 回 顧主要的行業(yè)趨勢和技術(shù)； 回答以上戰(zhàn)略問題： 你的機(jī)構(gòu)在這些市場中的聲譽(yù)如何？你希望它做成什么樣？這個產(chǎn)品或服務(wù)如何支持你的目標(biāo)？2.2 用戶剖析描述系統(tǒng)中每個不同的用戶。 用戶的類型可能是從權(quán)威到新手差距很大。 例如， 權(quán)威可能需要一個復(fù)雜、 靈活的支持跨平臺工具， 而一個新手可能需要一個易于使用、 用戶友好的 工具。對用戶的全面剖析覆蓋每種用戶的以下題目：1）技術(shù)背景和復(fù)雜程度；2）主要職責(zé)；3）為誰提交用戶產(chǎn)品；4）使

4、用戶的工作更容易或更困難的趨勢；5）影響成功的問題；6）目標(biāo)用戶對成功的定義以及用戶如何等到回報(bào)。2.3 用戶環(huán)境目標(biāo)用戶的工作環(huán)境的詳細(xì)描述。以下是一些建議：1）完成該任務(wù)涉及多少人？是否會變化？2）任務(wù)的周期是多長？其中每項(xiàng)活動需要多少時間？是否會變化？3）是否有一些獨(dú)特的環(huán)境約束：移動的、室外的、飛機(jī)上的，等等？4）現(xiàn)在正在使用哪種系統(tǒng)平臺？未來的平臺是什么？5）正在使用其他什么應(yīng)用系統(tǒng)？你的應(yīng)用系統(tǒng)是否能與這些系統(tǒng)集成？2.4 關(guān)鍵用戶需要列出用戶認(rèn)為的關(guān)鍵問題或需要。為每個問題澄清以下內(nèi)容：1）這個問題的原因是什么？2）現(xiàn)在是怎么解決的？3）用戶預(yù)期的解決技術(shù)方案是什么？重要的是理解

5、用戶對解決每個問題所放的相對重要性。分級和累積投票技術(shù)可以說明必須解決的問題以及每個問題強(qiáng)調(diào)的事物。2.5 替代品和競爭對手確定用戶認(rèn)為目前可得到的替代品?？砂ㄙ徺I對手的產(chǎn)品、 構(gòu)建一個全部是自己的解決技術(shù)方案或者維持現(xiàn)狀。列出所知的已有的以及即將得到的競爭對手的產(chǎn)品。包括最終用戶所理解的每位對手的強(qiáng)項(xiàng)和弱項(xiàng)。2.5.1 競爭對手13. 產(chǎn)品綜述這一部分對產(chǎn)品能力、 到其他應(yīng)用系統(tǒng)的接口以及系統(tǒng)配置等等提供一個高層視圖，通常由以下三個部分組成。3.1 產(chǎn)品前景這部分應(yīng)該合理地把該產(chǎn)品與其他相關(guān)產(chǎn)品及用戶的需求放在一起。如果產(chǎn)品是獨(dú)立的而且是完全獨(dú)立的， 就在這里說明它；如果產(chǎn)品是一個大型系統(tǒng)

6、的組件之一，那么這一部分應(yīng)該說明系統(tǒng)之間如何交互而且應(yīng)該確定相關(guān)的接口。一種展示大型系統(tǒng)主要組件、互連及外部接口的簡單方法就是利用框圖。3.2 產(chǎn)品定位陳述提供一個整體陳述，從最高層次歸納總結(jié)產(chǎn)品在市場上的獨(dú)特定位。Moore （1991）稱此為產(chǎn)品定位陳述，并推薦以下格式：為了（目標(biāo)客戶）誰（陳述需要或機(jī)遇）產(chǎn)品名是一個（產(chǎn)品分類）它（對主要優(yōu)點(diǎn)的陳述，即驅(qū)動購買的原因）不像（主要競爭替代品）我們的產(chǎn)品（對主要區(qū)別的陳述）產(chǎn)品定位陳述向所有相關(guān)人員說明了應(yīng)用系統(tǒng)的意圖以及工程的重要性。3.3 能力歸納總結(jié)歸納總結(jié)產(chǎn)品將提供的主要優(yōu)點(diǎn)和特征。例如，客戶支持系統(tǒng)的前景文檔可能會使用這一部分強(qiáng)調(diào)問

7、題建檔、路電和狀態(tài)報(bào)告一不提及各個功能需求的細(xì)節(jié)。組織特征，以便清單能夠被客戶或所有第一次閱讀文檔的人理解。一個簡單的表列出主要的優(yōu)點(diǎn)及其所支持的特征。客戶支持系統(tǒng)客戶收益支持特征收益1特征收益2特征收益3特征3.4 假定和相關(guān)條件列出所有一旦變更將影響整個產(chǎn)品前景的假設(shè)條件。例如，某個假定條件可能指出，指定用于軟件產(chǎn)品的硬件可得到某個特定的操作系統(tǒng)，如果該操作系統(tǒng)得不到，則前景必須變更。3.5 成本和定價對于將銷售給外部客戶的產(chǎn)品以及許多機(jī)構(gòu)內(nèi)使用的應(yīng)用系統(tǒng)，成本和定價將直接影響應(yīng)用系統(tǒng)的定義和實(shí)現(xiàn)。 在這一部分，把所有成本和相關(guān)的定價約束記錄下來。例如， 分銷 成本（磁盤、CD-ROM C

8、D母盤的編號）或者其他貨品銷售成本（手冊、打包）根據(jù)應(yīng)用的 性質(zhì)對于工程的成功可能無關(guān)也可能有實(shí)質(zhì)性影響。4. 特征屬性與需求一樣，特征也有屬性，提供附加的工程信息，用于評估、跟蹤、劃分優(yōu)先級、經(jīng) 管為實(shí)現(xiàn)提出的項(xiàng)。這一部分陳述所有建議在前景文檔中使用的屬性，描述所選擇的屬性及其意義，使各方都能更好地理解每個特征的背景。4.1 狀態(tài)在工程經(jīng)管團(tuán)隊(duì)協(xié)商和評審之后確定。狀態(tài)信息在工程基線定義過程中跟蹤進(jìn)程。1）建議的（proposed ）:描述正在對該特征進(jìn)行討論，但還沒有得到“正式渠道”的 審核與采納，“正式渠道”可以是一個由工程團(tuán)隊(duì)、產(chǎn)品經(jīng)管、用戶或客戶團(tuán)隊(duì)的代表組織的工作小組；2）批準(zhǔn)的（a

9、pproved ）:它的能力被斷定是有用和可行的，得到正式渠道的認(rèn)可并加 以實(shí)現(xiàn)；3）收編的（incorporated） ：已經(jīng)在某個特定時間收編入產(chǎn)品基線的特征；4.2 優(yōu)先級產(chǎn)品優(yōu)先級是由營銷人員、 產(chǎn)品經(jīng)理或商業(yè)分析人員設(shè)置的。 根據(jù)特征對最終用戶的相對優(yōu)先級把它們劃分等級打開了一個與客戶、 分析人員以及開發(fā)團(tuán)隊(duì)成員之間的對話。 優(yōu)先 級用于經(jīng)管廣度和確定開發(fā)優(yōu)先級。一種優(yōu)先級劃分模式如下：1）關(guān)鍵的（ critical ）：本質(zhì)特征。實(shí)現(xiàn)的失敗意味著系統(tǒng)將不能滿足客戶的需要。所有關(guān)鍵的特征必須在發(fā)布中實(shí)現(xiàn)，否則進(jìn)度將推遲。2）重要的（important ）：對于大多數(shù)應(yīng)用的系統(tǒng)效率和效

10、力都重要的特征。該功能無法容易地用其他方式實(shí)現(xiàn)。 如果缺少重要的特征， 可能影響客戶或用戶的滿意程度， 甚至影響收益，但發(fā)布不會因此而推遲；3）有用的（useful ）：在不太典型的應(yīng)用中有用的特征，但不經(jīng)常使用或者有其他合理的有效變通。如果發(fā)布中沒有這類特征也不會對客戶滿意程度或收益造成重大的影響4.3 工作量由開發(fā)團(tuán)隊(duì)設(shè)置， 用于經(jīng)管廣度和確定開發(fā)優(yōu)先級。 由于有些特征比其他特征要求更多的時間和資源， 因此對各特征采用團(tuán)隊(duì)數(shù)量或人周、 代碼行、 功能點(diǎn)等等進(jìn)行評估將是預(yù)測復(fù)雜度的最好辦法，從而可對在給定時間范圍內(nèi)能完成什么不能完成什么有一個預(yù)期。4.4 風(fēng)險由開發(fā)團(tuán)隊(duì)設(shè)置， 設(shè)置的依據(jù)是工

11、程經(jīng)歷意外事件的可能性， 如成本過高、 進(jìn)度延遲甚至工程被撤消等。許多工程經(jīng)理發(fā)現(xiàn)，把風(fēng)險分為高、中、低就已經(jīng)足夠了，盡管還可以再細(xì)一些。風(fēng)險通?？梢酝ㄟ^度量工程團(tuán)隊(duì)進(jìn)度預(yù)測的不確定性（范圍）進(jìn)行間接地評估。4.5 穩(wěn)定性由分析人員和開發(fā)團(tuán)隊(duì)設(shè)置，設(shè)置的依據(jù)是特征變更的可能性或團(tuán)對變更特征的理解。這個信息有助于建立開發(fā)優(yōu)先級或確定下一步中哪些附加啟發(fā)是適當(dāng)?shù)摹?.6 目標(biāo)當(dāng)布記錄特征將首先出現(xiàn)在哪一個產(chǎn)品版本中。 這個域可用于把特征分配到特定的基線版本中。當(dāng)把目標(biāo)版本與狀態(tài)域結(jié)合起來時， 團(tuán)隊(duì)可以建議、 記錄和討論該版本的各個特征，而不必把它們提交給開發(fā)。 只有一些狀態(tài)被設(shè)置為“收編的”特征并

12、且其目標(biāo)版本被定義的特征才能實(shí)現(xiàn)。 在發(fā)生廣度經(jīng)管時， 目標(biāo)版本的版本號會不斷增加， 于是該項(xiàng)仍然存在于前景文檔中，但被安排到以后的版本中去。在許多工程中，把特征分配給“特征團(tuán)隊(duì)”，負(fù)責(zé)進(jìn)一步啟發(fā)、書寫軟件需求和實(shí)現(xiàn)。這個簡單清單將幫助所有工程團(tuán)隊(duì)成員更好地了解自己的職責(zé)。4.8 原因這一文本域用來跟蹤所要求特征的來源。 特征的存在有很多特定的理由。 這個域記錄了 特征的解釋或?qū)忉尩囊谩?例如， 引用可以是產(chǎn)品需求規(guī)格說明的頁號和行號， 或是重要 客戶面談錄像帶上的一個分鐘標(biāo)志。5. 產(chǎn)品特征這一部分記錄產(chǎn)品特征。 特征提供了給用戶帶來利益所需要的系統(tǒng)能力， 每個特征都提供了一個滿足用戶需

13、要的服務(wù)。 例如， 問題跟蹤系統(tǒng)的一個特征可能是“提供走勢報(bào)告”的能力，趨勢報(bào)告可能繼續(xù)支持一個“更好理解工程狀態(tài)”的需要。因?yàn)榍熬拔臋n是由許多涉及人員審核的而且是達(dá)成共識的基礎(chǔ)。 所以特征應(yīng)該用用肪的自然語言描述。特征描述應(yīng)該簡短、精練，通常是1-2 個句子。為了有效經(jīng)管應(yīng)用的復(fù)雜度，我們建議：對于任何新系統(tǒng)或在原有系統(tǒng)上加強(qiáng)的系統(tǒng)，把能力抽象到較高層次產(chǎn)生大約 25-99 個特征。 這些特征是產(chǎn)品定義、 廣度經(jīng)管和工程經(jīng)管 的基本基礎(chǔ)。每個特征都可以在后面的規(guī)格說明中被更詳細(xì)地說明。在整個這一部分中，每一個特征都應(yīng)該是用戶、操作者或其他外部系統(tǒng)可以感知的。5.1 特征15.2 特征26.

14、關(guān)鍵用例描述一些關(guān)鍵用例， 可以是對體系結(jié)構(gòu)有意義或最方便幫助讀者理解系統(tǒng)如何使用的用例。7. 其他產(chǎn)品需求7.1 可應(yīng)用規(guī)范列出產(chǎn)品必須符合的規(guī)范，如法律和規(guī)章（ FDA FCC、通信規(guī)范（TCP/IP、ISDN）、 平臺兼容規(guī)范（Windows、UNIX）以及質(zhì)量和安全規(guī)范（UL、ISO、CMM。7.2 系統(tǒng)需求定義支持應(yīng)用所必須的所有系統(tǒng)需求。包括支持的主機(jī)操作系統(tǒng)、 網(wǎng)絡(luò)平臺、 配置、內(nèi) 存、外設(shè)以及軟件。許可和安裝問題對于開發(fā)工作有直接影響。 例如， 支持序列號、 口令安全或網(wǎng)絡(luò)許可證的需要必須創(chuàng)建其他開發(fā)過程中必須考慮的附加的系統(tǒng)需注。 安裝需求也會影響編碼或者產(chǎn) 生開發(fā)獨(dú)立安裝軟

15、件的需求。7.4 性能需求性能問題包括用戶負(fù)載因素、帶寬或通信能力、吞吐量、 準(zhǔn)確度、可靠性或在某些負(fù)載 條件下的響應(yīng)時間等。8. 建檔需求這一部分描述所有支持成功地部署系統(tǒng)必須開發(fā)的文檔8.1 用戶手冊描述用戶手冊的目的和內(nèi)容。討論其需要的長度、詳盡程序、 索引和詞匯表的需要、指 南及參考手冊策略，等等。還要指定格式和打印約束。8.2 在線幫助許多應(yīng)用系統(tǒng)都提供一個在線的幫助系統(tǒng)來輔助用戶。 這些系統(tǒng)的本質(zhì)是應(yīng)用系統(tǒng)開發(fā)所特有的，因?yàn)樗鼈儼丫幊蹋ㄈ绯溄樱┖图夹g(shù)書寫（如組織和表示）結(jié)合起來。許多人發(fā)現(xiàn)在在線幫助系統(tǒng)是工程中的工程，它從廣度經(jīng)管和計(jì)劃活動中直接受益。8.3 安裝指南、配置和自述文件對于一個全面的解決技術(shù)方案來說，有一個包括安裝指令和配置指南的文檔非常重要，而一個自述（Read Me）文件也通常作為規(guī)范組件而存在。自述文件中可能包括一