IT軟件項目文檔管理

第10章IT軟件項目文檔管理10.1軟件項目文檔管理概述10.2項目文檔的質(zhì)量10.3項目文檔準備10.4主要項目文檔2023/2/6上海海事大學計算機系110.1軟件項目文檔管理概述10.1.1項目文檔管理的概念10.1.2項目文檔的分類10.1.3過程文檔10.1.4產(chǎn)品文檔2023/2/6上海海事大學計算機系210.1.1項目文檔管理的概念1.文檔的地位是IT軟件項目開發(fā)中的重要組成部分對于項目開發(fā)的成功和項目的正常維護起著重要的保證和支持作用2.項目文檔的特點任何項目都有數(shù)量眾多的文檔一般：文檔數(shù)量的多少、規(guī)模的大小、結(jié)構(gòu)的復(fù)雜程度與所開發(fā)軟件的大小和復(fù)雜程度成正比開發(fā)成本一大部分發(fā)生在文檔的編制和準備過程中2023/2/6上海海事大學計算機系33.文檔的作用能作為開發(fā)組員之間交流溝通的媒介。能為軟件項目的維護工程師提供有關(guān)信息系統(tǒng)的資料和知識庫。能為項目管理者提供項目計劃、預(yù)算、開發(fā)進度等各方面的信息。能作為最終用戶或管理員的用戶手冊，使用戶知道如何使用、維護及管理系統(tǒng)。2023/2/6上海海事大學計算機系410.1.2項目文檔的分類1.分類：文檔可分為以下兩大類，即過程文檔和產(chǎn)品文檔過程文檔：是指那些記錄軟件項目開發(fā)和維護過程的文檔資料，項目的計劃、進度、過程質(zhì)量、組織及項目標準等都是過程文檔。產(chǎn)品文檔：是那些描述正在開發(fā)的產(chǎn)品的資料。這類文檔又可以分為從軟件工程師開發(fā)和維護系統(tǒng)的角度描述產(chǎn)品的系統(tǒng)文檔，以及主要以客戶為對象描述產(chǎn)品的用戶文檔。2023/2/6上海海事大學計算機系52.編寫過程文檔目的：在于所開發(fā)的產(chǎn)品能被很好地管理產(chǎn)品文檔一般在系統(tǒng)運行后才開始使用，同時它也對管理系統(tǒng)開發(fā)工作必不可少不同時期編寫的文檔代表在軟件開發(fā)過程中的一個重要階段里程碑。2023/2/6上海海事大學計算機系610.1.3過程文檔（1）1.

分類：軟件項目計劃、預(yù)測和進度安排文檔：這些文檔由項目經(jīng)理負責產(chǎn)生，以便預(yù)測和控制軟件的開發(fā)過程。相關(guān)報告：這些文檔用來報告在軟件開發(fā)過程中，資源是如何分配和利用的。標準報告：這些文檔規(guī)定了軟件過程應(yīng)該如何實現(xiàn)，這些可以是國際標準、國家標準、行業(yè)標準等。工作文檔：這些文檔是在項目開發(fā)中最主要的交流溝通工具，記錄了軟件項目開發(fā)中軟件工程師的想法等。備忘錄及電子信息：主要記錄了每天項目經(jīng)理和開發(fā)人員之間的詳細交流信息。2023/2/6上海海事大學計算機系72.過程文檔特點：大部分文檔都是已經(jīng)過時了的。過程文檔主要是軟件項目開發(fā)過程中的各種事件和信息的記錄。計劃可以是由周計劃、日計劃或月計劃組成，進度一般以周為單位進行報告，記錄軟件工程師的想法和目的備忘錄將不斷被改變。大多數(shù)信息在過時后將沒有多少使用價值，一般也就沒有再保存的必要，但也有例外，如測試計劃等在軟件開發(fā)過程中具有保存的價值，它是系統(tǒng)變更的基礎(chǔ)；設(shè)計報告也具有保存的價值，它為維護系統(tǒng)提供依據(jù)等。2023/2/6上海海事大學計算機系810.1.4產(chǎn)品文檔（1）1.特點：產(chǎn)品文檔主要描述已交付的軟件產(chǎn)品情況與過程文檔不同，產(chǎn)品文檔有很長的生命周期必須隨著產(chǎn)品一步步發(fā)展2.分類產(chǎn)品文檔可以分為用戶文檔和系統(tǒng)文檔用戶文檔以文檔資料形式告訴用戶如何利用該系統(tǒng)系統(tǒng)文檔主要為維護工程師服務(wù)2023/2/6上海海事大學計算機系93.注意：在軟件項目中，軟件的用戶并不完全相同，不同用戶面向的文檔也不一樣，必須產(chǎn)生不同的文檔來適應(yīng)不同的任務(wù)和水平的用戶在編輯文檔時，必須將最終用戶和系統(tǒng)管理員區(qū)分開最終用戶主要是使用軟件來完成一定的任務(wù)。他們只關(guān)心如何利用軟件來幫助他們完成工作，不關(guān)心計算機和軟件管理上其他細節(jié)系統(tǒng)管理員負責管理最終用戶使用的軟件……2023/2/6上海海事大學計算機系1010.1.4產(chǎn)品文檔（2）2023/2/6上海海事大學計算機系11系統(tǒng)管理員向?qū)到y(tǒng)評估員功能性描述描述提供的服務(wù)系統(tǒng)管理員安裝描述怎樣安裝系統(tǒng)新用戶初級使用手冊如何開始使用系統(tǒng)老用戶參考手冊所有系統(tǒng)功能的詳細描述系統(tǒng)管理員如何操作和維護系統(tǒng)圖10.1需要隨軟件系統(tǒng)發(fā)布而產(chǎn)生的部分用戶文檔10.1.4產(chǎn)品文檔（3）4.用戶文檔系統(tǒng)功能描述：簡要描述系統(tǒng)的需求和提供的服務(wù)。該文檔為系統(tǒng)提供一個總體的概念描述。用戶通過閱讀該文檔，可以確定是不是他們所需要的系統(tǒng)。初級使用手冊：為系統(tǒng)提供一個非正式的介紹，描述一些“常規(guī)”的使用操作。系統(tǒng)參考手冊：描述系統(tǒng)的功能設(shè)施及其用途，能為錯誤信息提供一個完整的列表，并且描述怎樣從發(fā)現(xiàn)的錯誤中恢復(fù)。系統(tǒng)參考手冊應(yīng)該是完整的和正式的。2023/2/6上海海事大學計算機系12系統(tǒng)安裝文檔：一般面向系統(tǒng)管理員，為系統(tǒng)管理員提供在特定環(huán)境下如何安裝系統(tǒng)的詳細說明。系統(tǒng)管理員手冊：主要提供當系統(tǒng)與其他系統(tǒng)交互時所產(chǎn)生的信息，及如何對這些信息進行反應(yīng)的說明。2023/2/6上海海事大學計算機系1310.1.4產(chǎn)品文檔（4）5.系統(tǒng)文檔：系統(tǒng)文檔包括所有描述系統(tǒng)是如何從需求報告到最終變成可接受的系統(tǒng)過程中，與分析、設(shè)計、實施等方面有關(guān)的技術(shù)文檔。主要包括：需求文檔及相關(guān)的基本原理說明。系統(tǒng)體系結(jié)構(gòu)文檔。對系統(tǒng)的每一個程序，都有相應(yīng)的程序體系結(jié)構(gòu)文檔。每個子系統(tǒng)的規(guī)范和設(shè)計說明書。2023/2/6上海海事大學計算機系14程序代碼列表。這些列表包括程序注釋、用來解釋代碼中復(fù)雜代碼段和采用的編碼方法等。描述每個程序怎樣驗證和驗證信息與需求之間關(guān)系的驗證文檔。維護指導(dǎo)文檔，主要描述系統(tǒng)已知的問題、軟件支持、硬件支持等信息，以便維護時使用。2023/2/6上海海事大學計算機系156.文檔編制的注意事項系統(tǒng)維護的要求：文檔與文檔之間的關(guān)系與依賴都應(yīng)該記錄在配置管理數(shù)據(jù)庫中修改代碼引起的文檔變化，應(yīng)該采用記錄文檔關(guān)系的軟件工具來支持文檔維護，當一個文檔變化引起其他文件變化是，提醒工程師2023/2/6上海海事大學計算機系1610.2項目文檔的質(zhì)量10.2.1項目文檔結(jié)構(gòu)10.2.2文檔標準10.2.3文檔書寫風格2023/2/6上海海事大學計算機系171.概述文檔質(zhì)量與程序質(zhì)量一樣重要沒有說明如何使用系統(tǒng)和理解系統(tǒng)的文檔，系統(tǒng)實用性會大打折扣高質(zhì)量文檔產(chǎn)生既不容易也不便宜，與編制高質(zhì)量的程序一樣困難2023/2/6上海海事大學計算機系1810.2.1項目文檔結(jié)構(gòu)（1）1.文檔結(jié)構(gòu)的基本原則文檔的內(nèi)容決定了文檔的結(jié)構(gòu)，文檔結(jié)構(gòu)隨項目不同而不同，但一般都要符合以下的基本原則：所有文檔（不論大小、長短）都應(yīng)該有封面，用來標識該項目文檔的作者、制作時間、文檔類型、配置管理、質(zhì)量確保信息和文檔的秘級等，還包括文檔的摘要、關(guān)鍵字及版權(quán)信息。如圖10.2。文檔應(yīng)分章節(jié)描述。如果文檔包括許多細節(jié)性參考信息，應(yīng)該有附錄。文檔應(yīng)該有難點注釋和詳細說明。文檔的結(jié)構(gòu)通常應(yīng)當是嚴整的，并且有一定的標準。2023/2/6上海海事大學計算機系192023/2/6上海海事大學計算機系2010.2.1項目文檔結(jié)構(gòu)（2）

文檔封面的主要信息：標題：項目：文檔ID：文檔類型：版本：日期：作者：是否被檢查：是/否是否被同意：N/A提交給CM：CM_ID：發(fā)布：密級：關(guān)鍵詞：圖10.2項目文檔封面的主要信息10.2.2文檔標準（1）1.重要性文檔標準是保證文檔質(zhì)量的基礎(chǔ)，根據(jù)一定的標準編寫文檔可以有一致的外觀、結(jié)構(gòu)和質(zhì)量等。2.類型過程標準：這種標準定義了高質(zhì)量文檔應(yīng)該遵守的過程產(chǎn)品標準：這種標準操縱文檔本身交互標準：通過電子郵件和文檔數(shù)據(jù)庫交換文檔變得越來越重要，交互標準使得所有的文檔都存在可比性。交互標準的使用允許文檔通過電子化的方式傳遞，能夠相互理解和規(guī)范，并且在最初的格式上進行再創(chuàng)作2023/2/6上海海事大學計算機系21過程標準定義了書寫文檔的方法，規(guī)定了書寫文檔時采用的軟件工具，同時也定義了高質(zhì)量文檔的質(zhì)量確保程序過程標準必須靈活文檔編制過程是一個不斷重復(fù)的過程，這個過程應(yīng)該直到一個可接受的質(zhì)量是才停止可接受的質(zhì)量水平依賴于文檔的種類和它潛在的用戶水平2023/2/6上海海事大學計算機系222023/2/6上海海事大學計算機系2310.2.2文檔標準（2）——文檔編制過程圖10.3文檔編制過程階段2：修改階段1：編制編寫最初文檔評審文檔整理評審意見修改文檔校對文字最終文檔確認最終文檔設(shè)計文檔復(fù)審文檔打印文檔打印備份文檔階段3：發(fā)布產(chǎn)品標準適用于在軟件開發(fā)過程中所產(chǎn)生的文檔。文檔應(yīng)該有一個統(tǒng)一的外觀，同一類文檔應(yīng)該有統(tǒng)一的結(jié)構(gòu)應(yīng)該基于更一般的行業(yè)標準2023/2/6上海海事大學計算機系2410.2.2文檔標準（3）文檔編制中涉及到的一些產(chǎn)品標準有：文檔識別標準：項目都要產(chǎn)生許多文檔，每一個文檔都要求有一個獨特的識別標準。對于正式的文檔，它的識別標準可以是由配置管理人員專門定義的；對于非正式的文檔，其識別標準可以由項目經(jīng)理來定義。文檔結(jié)構(gòu)標準：在軟件項目中每一種類型的文檔都有一種合適的結(jié)構(gòu)，結(jié)構(gòu)標準就用來定義這種結(jié)構(gòu)，可以采用傳統(tǒng)的頁碼、頁眉、頁腳和章節(jié)等。文檔解釋標準：文檔解釋標準定義了文檔的總體“建筑風格”，包括文檔中字體的大小、顏色及風格的定義等。文檔更新標準：系統(tǒng)的變更應(yīng)在文檔中反映，因此應(yīng)該采用一種連續(xù)的方法來表示系統(tǒng)變更，即在文檔中確定更新的標準。2023/2/6上海海事大學計算機系25文檔標準要適用于所有項目文檔及用戶文檔的最初版本。2023/2/6上海海事大學計算機系2610.2.3文檔書寫風格文檔的質(zhì)量依賴于編寫者的文字組織能力，好的文檔需要好的文筆編寫文檔時要注意以下問題:運用主動的而不是被動的語氣。運用正確的術(shù)語和語法結(jié)構(gòu)。句子不宜過長，盡量用短句。段落簡短。用詞簡潔，不要長篇累犢，質(zhì)量比數(shù)量更重要。簡明定義用到的專業(yè)術(shù)語。2023/2/6上海海事大學計算機系2710.2.3文檔書寫風格應(yīng)用標題和子標題。盡可能地逐條列舉事實。不要單純地參考數(shù)字、圖、表來理解信息，應(yīng)當有一定的說明和注釋。文檔要像程序一樣采用相同的方法進行檢測，在后期主要側(cè)重在錯誤的發(fā)現(xiàn)而不是錯誤的修改機制上2023/2/6上海海事大學計算機系2810.3項目文檔準備（1）1.階段文檔制作：文字處理器、文本格式器、表格和公式編輯器、繪圖工具包等。文檔修改：拼寫檢查器和風格檢查器。文檔產(chǎn)品發(fā)布：桌面發(fā)布包、技術(shù)工作包等。最常用的文檔工具是系統(tǒng)編輯器，它支持文檔的產(chǎn)生和修改過程。2023/2/6上海海事大學計算機系2910.3項目文檔準備（2）文檔管理系統(tǒng)：2023/2/6上海海事大學計算機系30文檔索引文檔管理系統(tǒng)配置管理系統(tǒng)文檔參考用戶請求圖10.4文檔管理文檔數(shù)據(jù)庫文檔管理系統(tǒng)可以維護關(guān)聯(lián)文檔的索引，并且從文檔的文本中產(chǎn)生索引。可以采用標準數(shù)據(jù)庫、配置管理工具和系統(tǒng)文件來建造。它是一個松散集成的系統(tǒng)，并且在部分系統(tǒng)里要求一定的原則。10.4主要項目文檔10.4.1項目開發(fā)立項報告10.4.2可行性研究報告10.4.3項目開發(fā)計劃報告10.4.4項目分析報告10.4.5項目設(shè)計報告10.4.6程序設(shè)計報告10.4.7項目測試報告10.4.8項目使用與維護手冊10.4.9項目評價報告10.4.10項目開發(fā)總結(jié)報告2023/2/6上海海事大學計算機系312023/2/6上海海事大學計算機系3210.4.1項目開發(fā)立項報告(1)概述：概述現(xiàn)行系統(tǒng)的組織結(jié)構(gòu)、功能、業(yè)務(wù)流程以及存在的主要問題。(2)新系統(tǒng)的目標：開發(fā)新系統(tǒng)的意義和新系統(tǒng)實現(xiàn)后的功能、技術(shù)指標、安全和保密性、新系統(tǒng)運行環(huán)境等。(3)經(jīng)費預(yù)測和經(jīng)費來源。(4)項目進度和完成期限。(5)驗收標準和方法。(6)移交的文檔資料。(7)開始可行性研究的組織隊伍、機構(gòu)與預(yù)算。(8)其他需要說明的有關(guān)問題。項目開發(fā)立項報告是在項目正式開發(fā)前，由開發(fā)單位提出或委托開發(fā)單位提出要開發(fā)的新系統(tǒng)的目標、功能、費用、時間、對組織機構(gòu)的影響等內(nèi)容的申請項目立項文檔。項目開發(fā)立項報告主要包括以下內(nèi)容

:2023/2/6上海海事大學計算機系3310.4.2可行性研究報告可行性研究報告主要包括以下內(nèi)容:(1)系統(tǒng)概述。(2)新系統(tǒng)的目標、要求和約束。(3)可行性研究的基本準則。(4)現(xiàn)行系統(tǒng)描述及現(xiàn)行系統(tǒng)存在的主要問題。(5)新系統(tǒng)對現(xiàn)行系統(tǒng)的影響。(6)投資與效益分析。(7)其他可選方案及國內(nèi)外同類方案的比較。(8)有關(guān)建議。可行性研究階段的文檔是可行性研究報告?？尚行匝芯繄蟾媸歉鶕?jù)對現(xiàn)行系統(tǒng)的調(diào)查、分析和研究，提出若干個系統(tǒng)的開發(fā)方案及其評價，供領(lǐng)導(dǎo)進行決策。2023/2/6上海海事大學計算機系3410.4.3項目開發(fā)計劃報告(1)概述：主要包括系統(tǒng)開發(fā)的主要目標、基本方針、參加人員、工作階段和內(nèi)容等。(2)開發(fā)計劃：系統(tǒng)開發(fā)各個工作階段或者子項目的劃分、任務(wù)、分工、負責人、計劃時間(開始及結(jié)束時間)、人力資源需求、資金及設(shè)備消耗、實際執(zhí)行情況等。可以用工作進度表、甘特圖、網(wǎng)絡(luò)圖及關(guān)鍵路徑法等工具輔助管理。(3)驗收標準：每項工作完成后驗收的標準，包括時間、資金、質(zhì)量等。(4)協(xié)調(diào)方法：項目開發(fā)中各個單位、階段之間的銜接、協(xié)調(diào)方法、負責人、權(quán)限等。項目開發(fā)計劃報告主要包括以下內(nèi)容

:2023/2/6上海海事大學計算機系3510.4.4項目分析報告(1)概述(2)系統(tǒng)需求(3)新系統(tǒng)的目標與新系統(tǒng)的功能(4)新系統(tǒng)的邏輯模型(5)新系統(tǒng)的運行環(huán)境(6)新系統(tǒng)的驗收標準與培訓計劃項目分析報告主要包括以下內(nèi)容

:2023/2/6上海海事大學計算機系3610.4.5項目設(shè)計報告(1)系統(tǒng)概述(2)系統(tǒng)總體結(jié)構(gòu)(3)計算機系統(tǒng)配置方案(4)代碼設(shè)計(5)文件/數(shù)據(jù)庫設(shè)計(6)輸入輸出設(shè)計(7)計算機處理過程設(shè)計(8)接口及通信環(huán)境設(shè)計(9)安全保密設(shè)計(10)數(shù)據(jù)準備(11)系統(tǒng)測試計劃(12)培訓計劃包括以下內(nèi)容

:2023/2/6上海海事大學計算機系3710.4.6程序設(shè)計報告(1)概述(2)程序結(jié)構(gòu)圖(3)程序控制圖(4)算法(5)程序流程圖(6)源程序(7)程序注釋及說明包括以下內(nèi)容

:2023/2/6上海海事大學計算機系3810.4.7項目測試報告(1)概述：說明項目測試的目的。(2)測試環(huán)境：有關(guān)軟、硬件、通信、數(shù)據(jù)庫、人員等情況。(3)測試內(nèi)容：系統(tǒng)、子系統(tǒng)、模塊的名稱、性能技術(shù)指標等。(4)測試方案：測試的方法、測試數(shù)據(jù)、測試步驟、測試中故障的解決方案等。(5)測試結(jié)果：測試的實際情況。(6)結(jié)論：項目功能評價、性能技術(shù)指標評價、結(jié)論。包括以下內(nèi)容

:2023/2/6上海海事大學計算機系3910.4.8項目使用與維護手冊(1)概述：主要包括系統(tǒng)功能、系統(tǒng)運行環(huán)境(軟硬件環(huán)境)、系統(tǒng)安裝等內(nèi)容。(2)使用說明：系統(tǒng)操作使用說明較為詳細地說明了操作的目的、過程、方式、輸入輸出的數(shù)據(jù)等。最好將系統(tǒng)操作的界面圖放入說明書中，便于使用者學習與操作。(3)問題解釋：解釋了系統(tǒng)使用中可能出現(xiàn)的問題及解決辦法，如非常規(guī)操作命令、系統(tǒng)恢復(fù)過程及意外情況、與開發(fā)單位的聯(lián)系方式等。包括以下內(nèi)容