5.7軟件文檔的質(zhì)量要求

一個好的文檔資料能起到多種有益的作用。如，有助于系統(tǒng)順利開發(fā)，有助于管理人員監(jiān)督和管理軟件開發(fā)，有助于用戶了解軟件的功能和正確操作流程，有助于維護(hù)人員進(jìn)行有效的維護(hù)。而一個質(zhì)量差的軟件文檔，不僅使讀者難以理解，給使用者造成許多不便，增加軟件成本，甚至可能造成更加有害的后果。因此，軟件編檔必須保證其質(zhì)量。造成軟件文檔質(zhì)量不高的原因多種多樣，但主要可以歸納為兩條：1.缺乏實踐經(jīng)驗，缺乏評價文檔質(zhì)量的標(biāo)準(zhǔn)；2.不重視文檔工作，或是對編檔工作安排不恰當(dāng)。最常見的就是，軟件開發(fā)時不重視編檔，最后卻搞突擊。1高質(zhì)量的軟件文檔應(yīng)當(dāng)具備以下幾方面的特點：1.針對性編檔前即能根據(jù)涉眾對象，按不同文檔類型、不同涉眾層次、不同分發(fā)策略，確定編檔目的、目標(biāo)、標(biāo)準(zhǔn)、方案、計劃和資源。2.精確性文檔行文應(yīng)十分確切、一致，沒有多義、重復(fù)、矛盾等現(xiàn)象。3.清晰性文檔力求簡潔，表述清晰，如有可能，則配以適當(dāng)圖表，以增強(qiáng)可閱讀性。4.完整性任何文檔都是完整的、獨立的，是自成體系的。5.靈活性前已多有述及，不再贅述。6.可追溯性軟件開發(fā)各階段編制的文檔與各自對應(yīng)階段完成的工作有緊密聯(lián)系，相鄰階段的文檔也會有一定的繼承關(guān)系，因此，必要時相關(guān)文檔能做到跟蹤追查。25.8軟件文檔編制技巧擁有規(guī)范準(zhǔn)確的軟件文檔，是每個軟件產(chǎn)品保證質(zhì)量所必須的必要條件，同時對軟件企業(yè)自身非常有利，也能夠讓用戶從中受益。而軟件產(chǎn)品的正確使用，也依賴于文檔的準(zhǔn)確可靠。那么，如何才能編制出好的文檔呢？下面是一些建議：1.從技術(shù)角度進(jìn)行文檔的編制和評價由于軟件文檔是作為軟件產(chǎn)品的技術(shù)資料的特點，因此編制時應(yīng)從技術(shù)角度著手，以忠實于技術(shù)事實為準(zhǔn)繩，保證編制步驟、描述內(nèi)容和使用圖表資料的準(zhǔn)確性。2.明確編檔人員的責(zé)任文檔質(zhì)量欠佳的主要原因之一就是責(zé)任不明確，沒有承認(rèn)編檔人員的勞動付出。因此，明確責(zé)任，明確編檔者的工作貢獻(xiàn)，是提高文檔質(zhì)量的有效途徑。33.讓編檔人員對開發(fā)項目有充分準(zhǔn)確的認(rèn)識由于軟件開發(fā)人員工作強(qiáng)度大、時間緊，所以不少企業(yè)大型項目的編檔工作就交由專職的編檔人員完成。但編檔人員對編檔對象了解的程度，尤其是了解的充分性和準(zhǔn)確性，將直接影響到編檔的準(zhǔn)確性。所以，為了讓專職編檔人員能夠編制出高質(zhì)量的產(chǎn)品文檔，應(yīng)該從以下幾個方面為他們提供條件：(1)將編檔人員組合進(jìn)開發(fā)小組(2)讓編檔人員多參加有關(guān)產(chǎn)品設(shè)計與開發(fā)的工作會議(3)讓編檔人員參與到技術(shù)要求、功能規(guī)劃及設(shè)計方案的開發(fā)工作中去(4)鼓勵編檔人員更多的了解有關(guān)產(chǎn)品及其相關(guān)的技術(shù)背景4.組織開發(fā)人員參與文檔評審軟件開發(fā)人員對產(chǎn)品方案、技術(shù)、結(jié)構(gòu)的掌握，對編檔工作有十分重要的意義，如何使得這些信息能被編檔人員所了解和把握，對軟件文檔的質(zhì)量至關(guān)重要。一個有效方法是，讓開發(fā)人員參與到文檔評審工作中去，增加開發(fā)人員對文檔的了解，增加開發(fā)人員與編檔人員的溝通交流，使編檔人員能及時從開發(fā)人員那里獲取所需信息，以保證編檔工作的順利進(jìn)行，保證編檔質(zhì)量。45.9軟件編檔的2個實例盡管軟件編檔存在著很多靈活性，但是，具體在實施編檔任務(wù)時，為了達(dá)到編檔質(zhì)量的目標(biāo)，還是需要控制這種靈活性。對于具體的軟件開發(fā)項目，需編制文檔的種類、詳細(xì)程度等，應(yīng)取決于開發(fā)組織的管理能力，以及項目自身的規(guī)模、復(fù)雜性和風(fēng)險等因素。而制訂一個可操作的編檔實施規(guī)定，用以規(guī)范在什么情況下應(yīng)該編制哪些文檔、文檔的質(zhì)量目標(biāo)等，是開發(fā)組織應(yīng)該首先完成的工作。由于國內(nèi)目前在這方面還缺乏成熟的經(jīng)驗，因此僅提供2個根據(jù)國外經(jīng)驗制訂的2個例子，以供參考。當(dāng)然，這2個例子也未必一定能與國內(nèi)現(xiàn)狀吻合，大家在參考時還應(yīng)與各自面臨的實際情況協(xié)調(diào)，才能獲取有益的結(jié)果。51.用求和法確定應(yīng)編制的文檔

該方法的要點是提出12個考慮因素來衡量一個應(yīng)用軟件，以及每個因素可能取值的范圍。任務(wù)負(fù)責(zé)人可用這12個因素對所要開發(fā)的程序進(jìn)行衡量，以確定每個因素的具體值。然后，把這12個因素的值相加，得到一個總和，就可以根據(jù)這個總和的值，來確定應(yīng)該編制的文檔的種類。具體例題：

隨著杭州逐步具備國際會展中心的基本功能，各類國際國內(nèi)、專業(yè)民用展覽，各種演出活動以及各種形式的會議、培訓(xùn)等活動將會越來越多，參與活動的人士也會有各種各樣，有的需要購買入場券，有的需要安排住宿，有的需要安排會議活動(如大會發(fā)言、小型研討、專題講座、新聞發(fā)布等，及場所)，有的需要安排游覽，也有的需要安排翻譯、領(lǐng)導(dǎo)接見或其它會務(wù)服務(wù)。對于部分會展、演出活動還需要在籌辦期間擬訂邀請賓客名單，發(fā)出邀請信，并對回執(zhí)進(jìn)行管理。購票、邀請賓客及被邀賓客回執(zhí)均可以在分布式環(huán)境中完成，會議期間的活動安排可以在網(wǎng)上實時發(fā)布，甚至部分會議活動被安排在網(wǎng)上實時直播。根據(jù)以上敘述，規(guī)劃設(shè)計一個簡單的會務(wù)管理系統(tǒng)，完成上述功能的管理需求。

求和法的具體表格在4.5節(jié)已給出，后面再列：6編號因素因素取值123451創(chuàng)新程度沒有－在不同設(shè)備上重編程序有限－只是具有更嚴(yán)格的要求很多－具有新的接口大量－應(yīng)用新的現(xiàn)代開發(fā)技術(shù)重大－應(yīng)用先進(jìn)的開發(fā)和管理技術(shù)2通用程度很強(qiáng)的限制－單一項目有限制－功能的范圍是參量化的有限的靈活性，允許格式上有些變化多用途、靈活的格式、有主題領(lǐng)域很靈活－能在不同設(shè)備上處理范圍廣泛的主題3應(yīng)用范圍局部單位(團(tuán)以下)本地應(yīng)用(師級)行業(yè)推廣(軍級)全國推廣(大軍區(qū))國際項目(全軍范圍)4應(yīng)用環(huán)境的變化沒有很少偶爾有經(jīng)常不斷5設(shè)備復(fù)雜性單機(jī)、常規(guī)處理單機(jī)、常規(guī)處理、擴(kuò)充的外設(shè)系統(tǒng)多機(jī)、標(biāo)準(zhǔn)的外設(shè)系統(tǒng)多機(jī)、復(fù)雜準(zhǔn)的外設(shè)系統(tǒng)和顯示主機(jī)控制系統(tǒng)多機(jī)自動I/O6參加開發(fā)人數(shù)1~2人3～5人6～13人11~18人19以上7開發(fā)投資(人月)<66~3636~120120~360>3608重要程度一般數(shù)據(jù)處理常規(guī)過程控制人身安全單位成敗國家安危9完成程序修改的平均時間2周以上1～2周3～7天1～3天24小時以內(nèi)10數(shù)據(jù)I/O平均時間2周以上1～2周1～7天1～24小時1小時以內(nèi)11編程語言高級語言高級語言帶少量的匯編高級語言帶相當(dāng)多的匯編匯編語言機(jī)器語言12并行軟件開發(fā)沒有有限中等程度很多全部7使用求和法的具體過程是：1.按前表中的12個因素衡量所要開發(fā)的程序，得到每個因素的值。在該問題中，我們通過分析可以得知各個因素的得分如下：(1)創(chuàng)新程度＝1 (7)開發(fā)投資(人月)＝1(2)通用程度＝3 (8)重要程度＝1(3)應(yīng)用范圍＝2 (9)完成程序修改的平均時間＝3(4)應(yīng)用環(huán)境的變化＝1 (10)數(shù)據(jù)I/O平均時間＝5(5)設(shè)備復(fù)雜性＝3 (11)編程語言＝1(6)參加開發(fā)人數(shù)＝1 (12)并行軟件開發(fā)＝22.把衡量所得的各個因素的值相加，得總和之值。在本例中，這個值 ∑＝2483.根據(jù)總和之值，從下表中，查出應(yīng)編制的文檔種類?？尚行匝芯繄蟾骓椖块_發(fā)計劃軟件需求說明書數(shù)據(jù)要求說明書概要設(shè)計說明書詳細(xì)設(shè)計說明書測試計劃用戶手冊操作手冊測試分析報告開發(fā)進(jìn)度月報項目開發(fā)總結(jié)程序維護(hù)手冊12～18√√*√16～26√√**√√√√√√24～38√√√**√√√√√√√36～50√√√**√√√√√√√√48～60√√√**√√√√√√√√√文檔的種類因素值總和表中：*，表示此文檔應(yīng)編制，但不必太正規(guī)；**，表示應(yīng)根據(jù)所開發(fā)軟件的實際需要來確定是否需要編制此文檔?，F(xiàn)在，可以依據(jù)表格，獲知本例需要編制的文檔種類，總共有9種之多。92.根據(jù)軟件規(guī)模大小確定應(yīng)編制的文檔為了避免在軟件開發(fā)過程中文檔編制的不足或過分，也為了避免前一種方法中對某些因素的把握出現(xiàn)誤判，一個簡便的方法是，把對軟件文檔的編制要求同軟件的規(guī)模聯(lián)系起來。這就是本例的出發(fā)點。這里，我們把軟件的規(guī)模分為四級：(1)小規(guī)模軟件，源碼行數(shù)小于5000；(2)中規(guī)模軟件，源碼行數(shù)約10000～50000；(3)大規(guī)模軟件，源碼行數(shù)約100000～500000；(4)超大規(guī)模軟件，源碼行數(shù)大于500000。對此，相應(yīng)規(guī)模軟件應(yīng)該編制的文檔種類，參見下表：10小規(guī)模軟件中規(guī)模軟件大規(guī)模軟件超大規(guī)模軟件軟件需求與開發(fā)計劃項目開發(fā)計劃可行性報告對應(yīng)大規(guī)模軟件所規(guī)定的文檔種類，再做進(jìn)一步細(xì)分項目開發(fā)計劃軟件需求說明軟件需求說明數(shù)據(jù)要求說明測試計劃測試計劃軟件設(shè)計說明軟件設(shè)計說明概要設(shè)計說明詳細(xì)設(shè)計說明數(shù)據(jù)庫設(shè)計說明使用說明使用說明用戶手冊操作手冊測試分析報告模塊開發(fā)卷宗模塊開發(fā)卷宗測試分析報告測試分析報告項目開發(fā)總結(jié)開發(fā)進(jìn)度月報開發(fā)進(jìn)度月報項目開發(fā)總結(jié)項目開發(fā)總結(jié)對于源碼行數(shù)在5000～10000、50000～100000的軟件，其文檔編制的種類介于兩級之間，可由項目負(fù)責(zé)人根據(jù)項目的具體情況，參照上表規(guī)定確定。11在本例中，我們再次使用上一個例子的問題，來嘗試確定其應(yīng)該編制的文檔種類。具體例題：隨著杭州逐步具備國際會展中心的基本功能，各類國際國內(nèi)、專業(yè)民用展覽，各種演出活動以及各種形式的會議、培訓(xùn)等活動將會越來越多，參與活動的人士也會有各種各樣，有的需要購買入場券，有的需要安排住宿，有的需要安排會議活動(如大會發(fā)言、小型研討、專題講座、新聞發(fā)布等，及場所)，有的需要安排游覽，也有的需要安排翻譯、領(lǐng)導(dǎo)接見或其它會務(wù)服務(wù)。對于部分會展、演出活動還需要在籌辦期間擬訂邀請賓客名單，發(fā)出邀請信，并對回執(zhí)進(jìn)行管理。購票、邀請賓客及被邀賓客回執(zhí)均可以在分布式環(huán)境中完成，會議期間的活動安排可以在網(wǎng)上實時發(fā)布，甚至部分會議活動被安排在網(wǎng)上實時直播。根據(jù)以上敘述，規(guī)劃設(shè)計一個簡單的會務(wù)管理系統(tǒng)，完成上述功能的管理需求。12根據(jù)基于LOC的軟件規(guī)模估算方法，我們可以按國際、國內(nèi)、專業(yè)展覽，會議、培