軟件文檔寫作08-文檔寫作2

5.7軟件文檔的質量要求

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

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

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

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