工程項目文檔編寫
引言
現在很多企業業務開展都離不開項目管理，項目文檔管理，是指在一個項目運作過程中将送出的各類文檔進行收集管理控制的過程。工程項目儲存的文檔要涵蓋項目可研、總體設計、基礎設計、詳細設計等整個項目周期，其中包括項目系統管理、文檔版本控制、文檔品質管理等管理内容。項目經理可以從項目文檔角度去把握項目進展情況。是以，工程項目文檔對于一個項目的順利進行有着至關重要的作用，其關鍵性不容忽視。
項目文檔學習路線圖
一.項目流程概述
每個項目大緻要經過調研項目、項目立項啟動、項目計劃、需求分析、需求變更、系統設計、建構開發、測試驗收、部署試運作上線和項目總結的不同階段。如圖1-1-1所示展示了整個項目開發的流程。
圖1-1-1 項目流程
1.項目角色
項目成員角色可以分為項目經理、産品經理、開發經理、測試經理。
l 項目經理為整個項目的核心，推動項目的整個進行，保證項目的傳遞。
l 産品經理主要負責設計項目需求，需求必須符合客戶的需要。
l 開發經理主要進行軟體設計以及代碼實作，順利的實作項目的要求。
l 測試經理主要負責對項目的品質進行審查，確定項目品質達到預期目标。
2.項目流程
1.項目立項
主要由項目經理組織項目人員進行項目啟動會議，明确項目背景、需要實作哪些功能、項目傳遞時間等，其主要目的是要項目組成員明确項目的情況。
2.項目計劃
由項目經理牽頭各角色成員配合，制定項目的開發計劃、項目的裡程碑、風險計劃、上線計劃、驗收計劃等。其主要目的是為了讓項目能夠準時傳遞，各過程可控。
3.需求階段
由産品經理根據項目的情況進行需求分析，整理出詳細的需求内容，包括需求規格說明書、産品設計圖、産品原型圖、産品高清設計圖等。項目需求在整個項目開發過程中十分重要。
4.設計階段
在需求階段之後即詳細的需求已經确認，由開發經理組織相關的開發團隊進行研發設計，該階段分為概要設計和詳細設計階段。先對項目的實作進行概要設計，即設計系統的總體架構以及使用到的技術評估。概要設計完成後，由開發經理組織相關的項目成員進行技術評審會議，技術評審通過後方可進行詳細設計，即詳細的代碼邏輯設計。
5.開發階段
在項目需求以及項目設計完成的情況下，由開發經理配置設定各開發成員的任務，由每個開發人員進行代碼開發實作。在開發實作過程中，各開發成員要進行代碼版本控制。確定代碼和系統版本可控。
6.測試階段
當項目功能實作後，且開發團隊已經自己測試無大問題後，就可以送出測試團隊進行最終的項目品質驗證。驗證的過程是一個疊代的過程，測試人員針對開發團隊釋出的内部測試版本，針對項目需求逐一認證，發現有問題的，則通過項目管理系統進行釋出，開發人員進行問題解決，測試人員進行回歸測試驗證。
7.試運作上線
當項目功能實作，且測試團隊無發現重大問題，達到可以上線的标準後。則由開發經理負責部署正式的上線系統，并且試運作一段時間。如果在試運作期間發現嚴重問題，則還需要進行問題修改，修改後再次進行試運作上線。
當項目試運作過程中發現無重大問題，滿足上線标準時，則項目正式上線運作，進行客戶傳遞。
8.項目總結
當項目進行試運作上線傳遞後，項目經理必須召集所有項目團隊成員進行項目總結會議，項目總結項目的得與失，吸取項目經驗。項目文檔及代碼在項目的每個階段都需要進行編寫，下方會有詳細的模闆以及編寫的要求，項目總結會議完成後，項目所有的資料，包括項目代碼、項目文檔、軟體及硬體資料都要及時歸檔到公司項目庫中。
下面就以某銀行系統容器雲平台建議的項目實戰案例進行介紹。
二．項目常用管理工具
1.項目立項工具（Microsoft Office Word）
Microsoft Office Word是微軟公司的一個文字處理器應用程式。Word給使用者提供了用于建立專業而優雅的文檔工具，幫助使用者節省時間，并得到優雅美觀的結果。一直以來，Microsoft Office Word都是最流行的文字處理程式。
作為Office套件的核心程式，Word提供了許多易于使用的文檔建立工具，同時也提供了豐富的功能集供建立複雜的文檔使用。哪怕隻使用Word應用一點文本格式化操作或圖檔處理，也可以使簡單的文檔變得比隻使用純文字更具吸引力。
2.項目計劃制定工具介紹（Excel）
Microsoft Excel是Microsoft為使用Windows和Apple Macintosh作業系統的電腦編寫的一款電子表格軟體。直覺的界面、出色的計算功能和圖表工具，再加上成功的市場營銷，使Excel成為最流行的個人計算機資料處理軟體。
3.系統設計工具介紹（Microsoft Office Visio）
Microsoft Office Visio是office軟體系列中的負責繪制流程圖和示意圖的軟體，是一款便于IT和商務人員就複雜資訊、系統和流程進行可視化處理、分析和交流的軟體。
4.文檔代碼管理工具（SVN工具使用介紹）
SVN的全稱是Subversion，即版本控制系統。它是最流行的一個開放源代碼的版本控制系統。作為一個開源的版本控制系統，Subversion管理着随時間改變的資料。這些資料放置在一個中央資料檔案庫（Repository）中。這個檔案庫很像一個普通的檔案伺服器，不過它會記住每一次檔案的變動。這樣就可以把檔案恢複到舊的版本，或是浏覽檔案的變動曆史。Subversion是一個通用的系統，可用來管理任何類型的檔案，其中包括程式源碼。
SVN采用用戶端/伺服器體系，項目的各種版本都存儲在伺服器上，程式開發人員首先将從伺服器上獲得一份項目的最新版本，并将其複制到本機，然後在此基礎上，每個開發人員可以在自己的用戶端進行獨立的開發工作，并且可以随時将新代碼送出給伺服器。當然也可以通過更新操作擷取伺服器上的最新代碼，進而保持與其他開發者所使用版本的一緻性。
5.項目總結工具（Microsoft Office PowerPoint）
Microsoft Office PowerPoint是指微軟公司的示範文稿軟體，如圖1-5-60所示。使用者可以在投影儀或者計算機上進行示範，也可以将示範文稿列印出來，制作成膠片，以便應用到更廣泛的領域中。
三．基本項目實施流程步驟
- 建立案例目标
- 進行案例分析
- 項目計劃
- 案例實施
- 項目團隊成立
- 項目立項
- 項目立項文檔
四．常用說明書
《概要設計說明書》
1引言
1.1寫目的：闡明編寫概要設計說明書的目的，指明讀者對象。
1.2項目背景：應包括
（1）項目的委托機關、開發機關和主管部門
（2）該軟體系統與其他系統的關系。
1.3定義：列出本文檔中所用到的專門術語的定義和縮寫詞的願意。
1.4參考資料：
（1）列出這些資料的作者、标題、編号、發表日期、出版機關或資料來源。
（2）項目經核準的計劃任務書、合同或上級機關的批文；項目開發計劃；需求規格說明書；測試計劃（初稿）；使用者操作手冊。
（3）文檔所引用的資料、采用的标準或規範。
2任務概述
2.1目标
2.2需求概述
2.3條件與限制
3總體設計
3.2總體結構和子產品外部設計
3.3功能配置設定：表明各項功能與程式結構的關系。
4接口設計
4.1外部接口：包括使用者界面、軟體接口與硬體接口。
4.2内部接口：子產品之間的接口。
5資料結構設計
6邏輯結構設計
7實體結構設計
8資料結構與程式的關系
9運作設計
9.1運作子產品的組合
9.2運作控制
9.3運作時間
10出錯處理設計
10.1出錯輸出資訊
10.2出錯處理對策：如設定後備、性能降級、恢複及再啟動等。
11安全保密設計
12維護設計
說明為友善維護工作的設施，如維護子產品等。
《詳細設計說明書》
1引言
1.1編寫目的：闡明編寫詳細設計說明書的目的，指明讀者對象。
1.2項目背景：應包括項目的來源和主管部門等。
1.3定義：列出本文檔中所用到的專門術語的定義和縮寫詞的願意。
1.4參考資料：
（1）列出有關資料的作者、标題、編号、發表日期、出版機關或資料來源。
（2）項目經核準的計劃任務書、合同或上級機關的批文；項目開發計劃；需求規格說明書；概要設計說明書；測試計劃（初稿）；使用者操作手冊。
（3）文檔所引用的資料、軟體開發的标準或規範。
2總體設計
2.1需求概述
2.2軟體結構：如給出軟體系統的結構圖。
3程式描述
3.1逐個子產品給出以下說明：
（1）功能
（2）性能
（3）輸入項目
（4）輸出項目
3.2算法：子產品所選用的算法。
3.3程式邏輯：較長的描述子產品實作的算法，可采用：标準流程圖；PDL語言；N-S圖；判定表等描述算法的圖表。
3.4接口
（1）存儲配置設定
（2）限制條件
3.5測試要點：給出測試子產品的主要測試要求。
《項目立項建議書》
1 産品介紹
1.1 産品定義
提示：用簡練的語言說明本産品“是什麼”，“什麼用途”。
1.2 産品開發背景
提示：從内因、外因兩方面闡述産品開發背景，重點說明“為什麼”要開發本産品。
（1）因方面着重考慮：開發方的短期、長期發展戰略；開發方的目前實力。
（2）外因方面着重考慮：市場需求及發展趨勢；技術狀況及發展趨勢。
（3）如果是合同項目，請說明項目的來源。
1.3 産品主要功能和特色
提示：
（1）給出産品的主要功能清單（Feature Lists）。
（2）說明本産品的特色。
1.4 産品範圍
提示：
（1）說明本産品“适用的領域”和“不适用的領域”。
（2）說明本産品“應當包含的内容”和“不包含的内容”。
2 市場概述
客戶需求
提示：
（1）闡述本産品面向的消費群體（客戶）的特征
（2）說明客戶對産品的功能性需求和非功能性需求
（3）說明本産品如何滿足客戶的需求，以及給客戶帶來什麼好處。
市場規模與發展趨勢
提示：
（1）分析市場發展曆史與發展趨勢，說明本産品處于市場的什麼發展階段。
（2）本産品和同類産品的價格分析
（3）統計目前市場的總額、競争對手所占的份額，分析本産品能占多少份額。
注意：引用資料應當寫明資料來源，最好有直覺的圖表。
3 産品發展目标
提示：說明本産品的短期目标和長期目标，目标必須清晰并且可以度量。
4 産品技術方案
産品體系結構
提示：
（1）繪制産品的體系結構
（2）闡述設計原理
（3）如果有多種體系結構，需比較優缺點。
4.2 關鍵技術
提示：闡述本産品的關鍵技術，評價技術實作的難易程度
5 産品優缺點分析
提示：綜合考慮本産品的功能、品質、價格、品牌等因素，分析優缺點。
6 Make-or-Buy決策
提示：
确定哪些産品部件應當采購、外包開發或者自主研發，說明理由。
分析相應的風險。
7 項目計劃
7.1 項目團隊
提示：說明項目團隊的角色、知識技能要求、建議人選、人數、工作時間。
7.2 軟體硬體資源估計
提示：
（1）估計項目所需的軟體和硬體資源，說明主要配置。
（2）說明以何種方式獲得，如“已經存在”、“可以借用”或“需要購買”等。
7.3 成本估計
提示：估計項目的“人力資源成本”、“軟硬體資源成本”、“商務活動成本”等等。
7.4 進度表
提示：繪制項目開發的進度表,參建附表
8 市場營銷計劃
提示：
（1）給出産品的赢利模式和價格結構。
（2）給出短期和長期銷售目标。
（3）規劃銷售方式和管道。
9 成本效益分析
提示：
（1）總成本是産品開發、營銷、維護的成本之和；
（2）效益包括“可量化的經濟效益”和“不可量化的好處”。
10 總結
提示：給出清晰的結論，便于上級上司決策。
《使用者需求說明書》
1 引言
1.1 編寫目的
本節描述編寫該使用者需求說明書的目的，并指出預期的讀者。
1.2 項目背景
本節描述使用者需求說明書中所定義的産品的背景和起源，以及同其他系統或其他機構的基本互相關系等。當在已有的系統上進行特性開發時，如果新特性與已有系統的特性之間存在關系，則應在本節說明其互相之間的關系。
1.3 術語定義
本節可列出本檔案中用到的專門術語的定義、外文首字母組詞的原詞組等。
1.4 參考資料
本節列舉編寫使用者需求說明書時所參考的資料或其他資源，這可能包括使用者合同、公司規範、技術書籍等。在這裡應該給出詳細的資訊，包括資料名稱、版本号、作者、日期、出版機關或資料來源，以友善讀者查閱這些文獻，可用以下格式表示，見表1：
表1 參考資料
| 資料名稱 | 版本号 | 作者 | 日期 | 出版機關/資料來源 | 備注 |
2 綜合描述
2.1 産品介紹
本節簡要描述産品的特性。
2.2 目标範圍
本節簡要描述産品的應用目标、作用範圍等。
2.3 使用者特性
本節可能包括本産品各類最終使用者的特點，如操作、維護等人員的知識水準和技術專長
《項目計劃書》電子表格（Xls）版本
《項目總結報告》
1引言
1.1 目的
[闡明編寫本總結報告的目的和意義，指出讀者對象。]
1.2 項目背景
[可包括本項目的來源、委托機關、開發機關和主管部門等。]
1.3 參考資料
2 項目基本情況
2.1項目産品
本條說明最終制成的産品，包括：
（1）源代碼。列出送出的源代碼版本和每個版本的功能。
（2）文檔：此處列出文檔清單。
（3）所建立的每個資料庫。
2.2主要功能和性能
簡要說明本産品所實際具有的主要功能和性能，對照項目開發計劃，需求說明書的有關内容，說明原定的開發目标是達到了、未完全達到、或超過了
2.3項目進度情況（見表1）
表1項目進度情況
| 實際 | 計劃 | 實際天數/計劃天數 |
| 項目周期 | ||
| 編碼周期 | ||
| 測試周期 | ||
| 完成時間 | ||
| 計劃調整次數 | ||
| 總體進度情況 | 項目實際比計劃提前/拖延 天 |
進度與計劃偏差的原因分析：
2.4遺留問題和風險
列出在項目開發計劃的要求範圍内，但尚未解決的問題以及可能遇到的風向問題。
3 開發工作評價
同計劃相比較，給出本項目的生産效率、産品品質和技術方法的綜合評價。
3.1 産品品質評價（見表2）
表2産品品質評價
| 缺陷數 | 嚴重缺陷數 | 嚴重缺陷比率 | 缺陷密度 | |
| 釋出時 | ||||
| 目标值 |
産品品質評價：
3.2技術方法評價
[總結該軟體項目或軟體産品開發時所采用的各項技術]
以下是示例：
（1）對開發工具的評價：
UBS-HotBilling使用TT作為記憶體資料庫，提高了應用處理的性能。試點割接上線後正常運作，并且為OCS系統上線提供了實踐依據，并積累了實施開發經驗。
（2）對架構技術的評價：從整個架構的整體使用效果來看并為達到預期的目的，我認為主要是由以下原因造成的：
架構本身存在有諸多不完善的地方，需要不斷地進行改進，但在改進的過程中沒有進行嚴格的控制，導緻架構的整體設計失控；
架構本身有這樣那樣的問題，有些問題是目前無法解決的；
架構是建構在PFC的基礎上的，項目組成員對PFC不是足夠的精通，為維護架構帶來難度。
建議：子產品化是産品化的基礎，也是降低成本、提高開發效率保證軟體品質的有效手段，需要有專人設計和維護架構。
（3）對設計方法的評價：資訊化項目的整體設計是由項目組全體成員完成的，鑒于我們目前的設計水準，我看還可繼續這種方法，對設計的方法和思路進行廣泛的借鑒，但一定要樹立設計的權威性，對設計的變更要進行嚴格的控制。
（4）對團隊開發的評價：從整體上講我們這個團隊的能力還可以，但我認為它的生産效率并不高也就是說團隊的整體建設不好，沒有明确的學習方向分工，使整個團隊在這段時間裡整體能力沒有太大的提高，我以前很想把我們的團隊培養成那種學習型的優秀團隊，可惜事與願違這項工作沒有取得什麼實效。
4 項目管理工作評價
4.1需求管理
需求變更情況：不同階段所發生的需求變更次數及發生變更的主要原因，具體見表3。
表3需求變更情況
| 變更發生的階段 | 需求變更次數 | 變更工作量（從申請開始到變更結束發生的工作量） |
| 使用者需求定義 | ||
| 軟體需求分析 | ||
| 設計 | ||
| 編碼 | ||
| 測試 | ||
| 維護 |
需求變更的主要原因：
4.2 計劃管理
計劃變更情況，具體見表4：
表4計劃變更情況
| 序号 | 變更發生階段 | 變更原因 | 變更内容 | 變更是否允許 |
| 1 | ||||
| 2 | ||||
| 3 |
5 經驗教訓
5.1 項目成功經驗
項目管理方面：
項目技術方面：
5.2 項目失敗教訓
項目管理方面：
項目技術方面：
5.3 對今後項目開發工作的建議
根據本項目的經驗和教訓，對于今後項目開發工作提出改進的建議。
《需求規格說明書》
對純軟體開發和比較大型軟體開發，要求根據軟體特點，由項目負責人專門進行軟體需求分析，從高層次來描述系統所要解決的問題，描述使用者需要怎樣的産品或服務，并對實作需求目标所需采取的措施和計劃進行描述。《需求說明書》可作為軟體總體設計的依據，具體編寫内容規範如下。
1 前言
1.1 目的
[闡明編寫需求分析的目的，指明使用者對象。（系統分析員、開發人員、測試人員）]
1.2 項目背景
[該軟體系統與其他系統的關系。 項目的開發機關及人員。]
1.3參考資料
[列舉出相關參考資料。]
項目概述
2.1 目标
叙述該項軟體開發的意圖、應用目标、作用範圍。解釋被開發軟體與其他有關軟體之間的關系。如果所定義的産品是一個更大的系統的一個組成部分，則應說明本産品與該系統中其他個組成部分之間的關系，為此可使用一張方框圖來說明該系統的組成和本産品同其他各部分的聯系和接口。
2.2 運作環境
2.2.1硬體裝置要求（主控端、目标機）,要描述軟體系統所需的硬體裝置的能力要求，如處理器的數量，記憶體容量，存儲媒體的數量，輸入，輸出裝置的數量，通信網絡結構，網絡的線路速度及通訊協定等。
2.2.2軟體環境要求，要列出支援軟體，包括要用到的作業系統、資料庫系統、編譯（或彙編）程式、測試支援軟體等。
2.3 使用者特性
列出本軟體的最終使用者的特點，充分說明操作人員、維護人員的教育水準和技術專長，以及本軟體的預期使用頻度。
2.4 條件與限制
2.4.1某些既成事實的限制（硬體、軟體等）
2.4.2整個大環境的情況
2.4.3某些規定的限制
3 性能需求
3.1 資料存儲要求
确定軟體的存儲容量要求，如處理的記錄數和處理資料的最大容量等。
3.2 管理能力的要求
3.3 時間特性
如響應時間、更新處理時間、資料轉換與傳輸時間（誤碼率）、運作時間等。
3.4 适應性
在操作方式、運作環境、與其他軟體接口以及開發計劃等發生變化時，應具有的适應能力。
4 功能需求
4.1 功能劃分
描述整個軟體在職能上應做什麼，應滿足哪些功能要求
4.2 功能描述
較長的描述每一條功能，用文字、圖形、邏輯或數學方法描述。
5 資料需求
對資料進行描述時可把資料分為靜态資料和動态資料。所謂靜态資料，指在運作過程中主要作為參考的資料，他們在很長的一段時間内不會變化，一般不随運作而改變。所謂動态資料，包括所有在運作中要發生變化的資料以及在運作中要輸入、輸出的資料。
5.1 靜态資料
列出所有作為控制或參考用的靜态資料元素。
5.2 動态資料
列出動态輸入資料元素（包括在正常運作中或聯機操作中要改變的資料）。
5.3 資料限制
列出若要進一步擴充資料或更充分地使用資料，而對資料要求提出的限制（如檔案、記錄和資料元素的最大容量或最多個數），特别應強調在設計和開發中被确定為臨界的那些限制。
5.4 資料庫描述
說明為滿足上述資料要求，資料庫應滿足的功能、性能、可靠性要求。
6 資料采集（根據具體軟體可選）
6.1 要求和範圍
6.1.1輸入源：說明資料來自操作員，還是其他分系統或輸入裝置。
6.1.2接受者：應區分出如下種類，輸入到系統，經處理後基本上無變化再輸出的資料。輸入到系統，但不再輸出的資料。由程式生成後輸出的資料。
6.1.3臨界值：指出資料元素的範圍，如一個轉折點，臨界值等。
6.1.4量綱：對數值量，應規定資料元素的增量，度量機關，測量機關的零點和值域；對于非數字量值，要用符号表示一些法定的值及他們之間的關系。
6.1.5換算因子：給出經模拟轉換或數字轉換處理的實測量的換算因子。
6.1.6資料更新頻度：對同步資料，應給出輸入，輸出的更新頻度，對異步資料，也要給出頻度平均值或變化的某種度量。
6.2 資料采集和傳遞方式：
較長的描述采集過程，包括資料格式，傳輸媒體和輸入輸出時間特性。
7 接口需求
7.1 使用者接口
如螢幕格式、報表格式、菜單格式、輸入輸出時間等。
7.2 硬體接口
說明該軟體同硬體之間的配合關系等。
7.3 軟體接口
說明該軟體同其他軟體之間的接口、資料通信協定等。
8 可靠性需求
8.1餘量需求
在需求分析時，應給安全關鍵軟體留有足夠餘量，這些餘量包括：存儲量，輸入輸出通道的吞吐能力以及處理時間等。例如，對整個計算機系統而言，推薦的存儲量，輸入輸出通道的吞吐能力及處理時間餘量不少于20%。
8.2 故障處理要求
列出可能的軟體、硬體故障以及對各項性能而言所産生的後果和對故障處理的要求
8.3 不允許發生的事件
明确列出所有在軟體運作過程中絕對不允許發生的事件，如關鍵判别式決不允許誤判等，以作為設計限制。
8.4 可靠性名額的驗證（可選）
對有可靠性名額的軟體，在确定了軟體的功能性需求後，應考慮該軟體的可靠性名額是否能達到以及是否能夠驗證。如果可靠性名額不能達到或者不能驗證，那麼，需求分析人員應向上級主管部門彙報，以期得到其他的解決方法；如果軟體的可靠性名額既能達到又能驗證，那麼，需求分析人員應同使用者密切配合，确定軟體的功能剖面，并制定軟體可靠性測試計劃。
9 其他需求
如可使用性、可維護、可移植性，開發平台的需求等。