3.軟件開發(fā)文檔管理規(guī)范

軟件項目管理培訓講座系列之三——文檔管理規(guī)范內容提要文檔的分類和等級文檔管理的原則和方法文檔示例與討論2024年9月12日軟件項目管理培訓之三——文檔規(guī)范2為什么需要文檔管理？項目管理的依據(jù)了解進度、分析問題，提供項目可預見性工作交流的憑證口說無憑，立字為據(jù)軟件測試的基礎沒有文檔，測試人員無法展開工作培訓用戶的參考幫助外界人員了解項目內幕技術支持的幫手幫助技術支持人員熟悉系統(tǒng)、分析錯誤、解決問題記錄歷史的必須軟件最大的價值在于可復用性2024年9月12日軟件項目管理培訓之三——文檔規(guī)范3為什么需要文檔管理？2024年9月12日軟件項目管理培訓之三——文檔規(guī)范4按規(guī)范要求生成一整套文檔的過程，就是按照軟件開發(fā)規(guī)范完成一個軟件開發(fā)的過程。編寫文檔的基本思路明確文檔范圍，避免空泛浮躁大而全的文檔是沒有用的定位讀者角度，防止對牛彈琴以讀者能夠理解作為編寫文檔的標準規(guī)范名詞稱謂，保持前后一致統(tǒng)一的名詞和稱謂，會降低文檔的歧義性注重版本控制，切忌顧此失彼不同階段的文檔記錄了項目開發(fā)的完整過程應用圖文表格，保證內容清晰簡潔的圖形和表格勝過前言萬語2024年9月12日軟件項目管理培訓之三——文檔規(guī)范5文檔的分類（1）

類型讀者時間

可行性研究報告管理/研發(fā)人員可行性研究與計劃階段

項目開發(fā)計劃管理/研發(fā)人員可行性研究、需求分析階段設需求規(guī)格說明書研發(fā)人員需求分析階段計功能規(guī)格說明書研發(fā)人員需求分析階段開概要設計說明書研發(fā)/維護人員設計階段發(fā)詳細設計說明書研發(fā)/維護人員設計階段類數(shù)據(jù)庫設計說明書研發(fā)/維護人員設計階段

模塊開發(fā)卷宗管理/研發(fā)/維護人員實現(xiàn)、測試階段

測試計劃研發(fā)人員需求分析、設計階段

測試分析報告研發(fā)/維護人員測試階段管開發(fā)進度月報管理人員貫穿整個開發(fā)過程理項目開發(fā)總結管理人員測試階段類職責定義管理人員可行性研究與計劃階段

進度變更記錄管理人員隨時產用戶指南用戶需求分析、設計、實現(xiàn)階段品操作手冊用戶設計、實現(xiàn)階段類信息廣告用戶測試階段2024年9月12日軟件項目管理培訓之三——文檔規(guī)范6文檔的分類（2）文件階段可行性研究與計劃階段需求分析階段設計階段實現(xiàn)階段測試階段運行與維護階段數(shù)據(jù)需求說明書

項目開發(fā)計劃

軟件需求說明書

數(shù)據(jù)需求說明書

測試計劃

概要設計說明書

詳細設計說明書

數(shù)據(jù)庫設計說明書

模塊開發(fā)卷宗

用戶手冊

操作手冊

測試分析報告

開發(fā)進度月報

項目開發(fā)總結

2024年9月12日軟件項目管理培訓之三——文檔規(guī)范7文檔的分類（3）2024年9月12日軟件項目管理培訓之三——文檔規(guī)范8開發(fā)文檔可行性研究報告項目開發(fā)計劃模塊開發(fā)卷宗測試分析報告需求規(guī)格說明書功能規(guī)格說明書概要設計說明書詳細設計說明書數(shù)據(jù)庫設計說明書測試計劃文檔的分類（4）2024年9月12日軟件項目管理培訓之三——文檔規(guī)范9產品文檔用戶指南操作手冊用戶指南產品手冊文檔的分類（5）2024年9月12日軟件項目管理培訓之三——文檔規(guī)范10管理文檔開發(fā)進度月報項目開發(fā)總結職責定義進度變更記錄文檔的等級（1）確定文檔質量等級根據(jù)項目資源、項目大小和風險確定每個文檔的格式及詳細程度文檔格式和文檔內容同樣重要必須保證文檔的質量，文檔管理才有意義2024年9月12日軟件項目管理培訓之三——文檔規(guī)范11文檔的等級（2）文檔按照質量可劃分為四個等級：最低限度文檔（1級文檔）適合開發(fā)工作量低于一個人月的開發(fā)者自用程序包含程序清單、開發(fā)記錄、測試數(shù)據(jù)和程序簡介內部文檔（2級文檔）適合于沒有與其他用戶共享資源的專用程序1級文檔內容，加上足夠的注釋和說明2024年9月12日軟件項目管理培訓之三——文檔規(guī)范12文檔的等級（3）文檔按照質量可劃分為四個等級：工作文檔（3級文檔）適合于由同一單位內若干人聯(lián)合開發(fā)的程序，或可被其他單位使用的程序正式文檔（4級文檔）適合那些要正式發(fā)行供普遍使用的軟件產品關鍵性程序或具有重復管理應用性質（如工資計算）的程序需要4級文檔2024年9月12日軟件項目管理培訓之三——文檔規(guī)范13內容提要文檔的分類和等級文檔管理的原則和方法文檔示例與討論2024年9月12日軟件項目管理培訓之三——文檔規(guī)范14文檔管理的基本原則完整性原則項目文檔集應覆蓋軟件開發(fā)的完整流程簡潔性原則編寫文檔不應浪費過多的時間和經(jīng)歷有效性原則文檔必須能夠起到輔助決策、指導參考的作用延續(xù)性原則文檔的變化必須有合理依據(jù)，保持連續(xù)發(fā)展2024年9月12日軟件項目管理培訓之三——文檔規(guī)范15文檔管理的內容建立文檔規(guī)范，培養(yǎng)良好習慣制定編寫計劃，明確編寫責任檢查文檔質量，提高利用效率控制文檔范圍，保護知識產權實施版本控制，有效記錄歷史2024年9月12日軟件項目管理培訓之三——文檔規(guī)范16文檔管理方法：如何命名？命名規(guī)范的重要性統(tǒng)一的對外形象（舉例）有效的文檔分類（舉例）快速的文檔查找（舉例）命名規(guī)則的制定并無統(tǒng)一規(guī)則，依據(jù)項目環(huán)境自定義技巧1：確定統(tǒng)一的空白封面和項目名稱技巧2：同類型多個文檔的命名方法技巧3：文檔存儲和管理的方法2024年9月12日軟件項目管理培訓之三——文檔規(guī)范17文檔管理方法：如何保證內容完整？內容殘缺的體現(xiàn)缺少項目背景和內容目錄（舉例）缺少表格和示意圖（舉例）缺少對思想的闡述和問題的分析（舉例）保證內容完整的方法技巧1：提供統(tǒng)一的項目背景資料技巧2：培養(yǎng)一致的文檔編寫習慣技巧3：明確要求表格和圖形的使用方式2024年9月12日軟件項目管理培訓之三——文檔規(guī)范18文檔管理方法：如何寫好需求分析做好需求分析的前提條件客戶應用環(huán)境的了解市場主流與技術主流的了解客戶現(xiàn)有需求的總結和潛在需求的挖掘完成需求分析的過程第一步：項目建議書（Proposal）第二步：市場與技術調研報告（M&TReport)第三步：需求變更風險分析第四步：需求分析初稿2024年9月12日軟件項目管理培訓之三——文檔規(guī)范19文檔管理方法：如何寫好概要設計做好概要設計的前提條件客戶需求細節(jié)的了解技術重點和難點的分析系統(tǒng)結構的設計與劃分完成概要設計的過程第一步：功能描述（FunctionDescription）第二步：功能定義（FunctionSpecification）第三步：重點難點問題解決思路第四步：概要設計草案2024年9月12日軟件項目管理培訓之三——文檔規(guī)范20文檔管理方法：如何寫好詳細設計詳細設計的底線是什么？主要處理流程的詳細說明對外接口的詳細說明主要邏輯結構和數(shù)據(jù)結構的詳細說明完成詳細設計的過程第一步：流程定義（ControlFlow）第二步：數(shù)據(jù)結構定義（DataFlow)第三步：接口定義（APISpecification）第四步：詳細設計草案2024年9月12日軟件項目管理培訓之三——文檔規(guī)范21文檔管理方法：如何寫好里程碑報告里程碑報告的內容預期目標的解釋和說明已完成工作的說明進度情況、測試結果的分析和說明下一步工作的重點和難點完成里程碑報告的過程第一步：分析前一個里程碑報告的內容第二步：說明當前里程碑的主要進展第三步：總結存在的問題、困難和障礙第四步：列出下一個里程碑的主要工作計劃2024年9月12日軟件項目管理培訓之三——文檔規(guī)范22文檔管理方法：確定最小文檔集如何確定最小文檔集重要認識：最小文檔集不是指最簡單文檔集最重要、最必須的文檔組成最小文檔集如何實現(xiàn)最小文檔集人員分工：多人協(xié)作完成一份文檔文檔格式：提供統(tǒng)一易用的模板內容組織：合并細節(jié)結構，保持總體完整2024年9月12日軟件項目管理培訓之三——文檔規(guī)范23反思：為什么中國人不善于寫文檔？文化背景的原因官修史與私修史：從孔子談起封建專制與思想禁錮：焚書坑儒和文字獄現(xiàn)代教育的原因缺乏方法教育和人格教育缺乏法律意識和嚴謹態(tài)度官本位、錢本位的價值觀2024年9月12日軟件項目管理培訓之三——文檔規(guī)范24內容提要文檔的分類和等級文檔管理的原則和方法文檔示例與討論2024年9月12日軟件項目管理培訓之三——文檔規(guī)范25文檔編寫技巧文檔排版方法問題：你會用MSWord嗎？圖表制作方法問題：你會用MSVisio和MSExcel嗎？文檔分類結構問題：如何設計良好的文件夾結構？文檔命名方式問題：如何對自己的項目進行文檔命名？2024年9月12日軟件項目管理培訓之三——文檔規(guī)范26文檔示例與討論需求分析文檔示例研發(fā)類項目概要設計與詳細設計示例應用類項目概要設計與詳細設計示例數(shù)據(jù)庫與數(shù)據(jù)倉庫類設計文檔示例測試計劃與測試案例類文