社會的發(fā)展對軟件工程師提出了越來越高的要求，不僅要求他們具備良好的知識背景、較強的動手能力，還要求他們具有很好的溝通與表達能力。從培養(yǎng)和訓(xùn)練軟件工程師的書面溝通能力這一主旨出發(fā)，本書介紹了軟件技術(shù)文檔撰寫的基本原則、常用的文檔類型，以及收集信息和書寫文檔的策略，以便使讀者能按照標(biāo)準(zhǔn)的格式恰當(dāng)?shù)厥褂帽砀瘛D和參考文獻等，書寫出清晰、簡明和準(zhǔn)確的技術(shù)文檔和個人總結(jié)，并能評審書面文檔以發(fā)現(xiàn)各種問題。本書要求讀者具備一定的軟件工程知識。
前言
軟件文檔隨著軟件的產(chǎn)生而產(chǎn)生，隨著軟件工程的提出和發(fā)展而不斷得到規(guī)范，并且軟件文檔也成為軟件工程各個階段里程碑的重要標(biāo)志之一。但在實際軟件開發(fā)過程中，由于人為因素以及時間和成本的限制，導(dǎo)致軟件文檔資料通常既不完整也不合格，進而對軟件開發(fā)和后期維護造成影響。
本書旨在將軟件工程的基礎(chǔ)理論、實踐和文檔寫作緊密結(jié)合，以提供一個統(tǒng)一分層的軟件文檔寫作體系； 將有關(guān)軟件工程理論、軟件文檔寫作方法的敘述、分析和應(yīng)用有機地結(jié)合，使之形成一個較完整的軟件文檔寫作方法體系； 對軟件文檔管理給予系統(tǒng)的介紹，從而充實和豐富傳統(tǒng)的軟件文檔寫作。
本書是作者十多年來從事軟件工程教學(xué)、理論與實踐研究的學(xué)習(xí)心得和工作總結(jié)，且匯入了一些企業(yè)的軟件文檔規(guī)范和閱讀國內(nèi)外大量相關(guān)著作和論文的體會。它以分析的觀點、實踐的角度，站在開發(fā)與應(yīng)用的立場來進行討論，希望不僅說明軟件文檔“是什么”，還進一步分析“為什么”，且討論“如何做”，使讀者不僅能“知其然”，還能“知其所以然”，懂得“如何應(yīng)用”。它不僅包括了軟件工程各個階段的文檔，還從質(zhì)量保證和配置管理的角度說明對文檔的管理。
全書共分10章，第1章介紹軟件工程基礎(chǔ)以及軟件文檔和軟件過程之間的關(guān)系； 第2章介紹項目規(guī)劃類文檔寫作，包括商業(yè)計劃書、可行性研究報告、項目方案書和項目開發(fā)計劃等； 第3章介紹需求類文檔寫作，主要涉及需求規(guī)格說明書； 第4章介紹設(shè)計類文檔寫作，包括架構(gòu)文檔、概要設(shè)計說明書、詳細設(shè)計說明書、數(shù)據(jù)庫設(shè)計說明書和界面設(shè)計文檔等； 第5章介紹測試類文檔寫作，包括測試用例、測試計劃和測試分析報告； 第6章介紹項目結(jié)束類文檔，包括用戶培訓(xùn)計劃、用戶手冊、產(chǎn)品手冊和項目總結(jié)報告等； 第7章介紹項目管理過程類文檔，包括項目風(fēng)險管理、時間進度管理、估算管理和項目的月報與周報等； 第8章介紹質(zhì)量保證相關(guān)文檔； 第9章介紹軟件文檔配置管理的方案，對軟件文檔進行版本控制； 第10章介紹企業(yè)軟件文檔的管理； 最后是附錄，給出了若干軟件文檔的模板供讀者參考。
本書在編寫過程中力求語言通俗易懂，文字簡潔明了，便于自學(xué)者閱讀，除可作為高校計算機專業(yè)和軟件工程專業(yè)的教材外，也可供從事計算機工作的工程技術(shù)人員及其他自學(xué)者參考。
本書的手稿已在軟件學(xué)院對本科生和研究生講授了多次，他們有的閱讀了原講義，并提出過意見。
對于書中的許多內(nèi)容，作者的多屆研究生、本科生曾從各個不同的方面、以不同的形式做了許多工作。在此，一并向他們表示誠摯的謝意。
誠如前面所說，書中的許多方面是作者的學(xué)習(xí)與實踐體會，有的內(nèi)容是作者的研究心得，再加之作者才學(xué)疏淺，水平與能力有限，因此書中見仁見智之說、不妥或不足之處，恐在所難免，切盼學(xué)術(shù)界同仁、軟件從業(yè)人員和各方讀者不吝賜教。
作者
2016年8月
第1章軟件工程基礎(chǔ)
1.1軟件與軟件工程
1.1.1軟件定義與軟件特點
1.1.2軟件危機與軟件工程
1.2軟件過程
1.2.1瀑布模型對應(yīng)的軟件過程
1.2.2以架構(gòu)為核心的軟件過程
1.3軟件過程中的文檔
1.3.1軟件文檔
1.3.2撰寫軟件文檔的目的與作用
1.3.3軟件文檔的范圍及分類
1.3.4項目開發(fā)與文檔的關(guān)系
1.3.5軟件過程角色與文檔的關(guān)系
1.3.6軟件過程中的文檔編制
1.3.7撰寫軟件文檔應(yīng)考慮的因素
1.3.8軟件文檔的管理
第2章項目規(guī)劃類文檔寫作
2.1項目立項過程
2.2商業(yè)計劃書
2.2.1商業(yè)計劃書寫作要求
2.2.2商業(yè)計劃書內(nèi)容框架
2.3可行性研究報告
2.3.1可行性研究報告寫作要求
2.3.2可行性研究報告內(nèi)容框架
2.4項目方案書
2.4.1項目方案書寫作要求
2.4.2項目方案書內(nèi)容框架
2.5項目開發(fā)計劃
2.5.1項目開發(fā)計劃寫作要求
2.5.2項目開發(fā)計劃內(nèi)容框架
第3章需求類文檔寫作
3.1需求概述
3.2軟件需求的分類
3.3需求過程
3.3.1需求分析
3.3.2需求過程的管理
3.3.3需求獲取的流程
3.3.4需求管理的角色
3.4需求說明書的撰寫要求
3.4.1需求文檔的文字敘述要求
3.4.2對用例說明的要求
3.4.3非功能需求的說明要求
3.5需求說明書內(nèi)容框架
3.6需求原型工具Axure
第4章設(shè)計類文檔寫作
4.1軟件設(shè)計過程
4.2軟件架構(gòu)設(shè)計
4.2.1架構(gòu)的概念
4.2.2以架構(gòu)為中心的迭代開發(fā)周期模型
4.2.3領(lǐng)域建模
4.2.4非功能需求驅(qū)動的架構(gòu)設(shè)計
4.3軟件架構(gòu)文檔
4.3.1軟件架構(gòu)文檔寫作要求
4.3.2軟件架構(gòu)文檔內(nèi)容框架
4.4概要設(shè)計說明書
4.4.1概要設(shè)計說明書寫作要求
4.4.2概要設(shè)計說明書內(nèi)容框架
4.5詳細設(shè)計說明書
4.5.1詳細設(shè)計說明書寫作要求
4.5.2詳細設(shè)計說明書內(nèi)容框架
4.6數(shù)據(jù)庫設(shè)計說明書
4.6.1數(shù)據(jù)庫設(shè)計的步驟
4.6.2數(shù)據(jù)庫設(shè)計說明書內(nèi)容框架
4.7用戶界面設(shè)計文檔
第5章測試類文檔寫作
5.1測試過程
5.1.1測試概述
5.1.2集成測試過程
5.1.3系統(tǒng)測試過程
5.2測試用例的撰寫
5.2.1測試用例寫作要求
5.2.2測試用例內(nèi)容框架
5.3測試計劃
5.4測試分析報告
第6章項目結(jié)束類文檔寫作
6.1部署過程
6.2用戶培訓(xùn)計劃
6.3開發(fā)組織內(nèi)部的培訓(xùn)課程
6.4用戶手冊
6.4.1用戶手冊要求
6.4.2用戶手冊內(nèi)容框架
6.5產(chǎn)品手冊要求
6.6項目總結(jié)
6.6.1項目總結(jié)要求
6.6.2項目總結(jié)報告內(nèi)容框架
第7章項目管理過程類文檔寫作
7.1項目管理過程
7.2項目風(fēng)險管理
7.3時間進度管理
7.4項目估算管理
7.5項目管理過程文檔
第8章質(zhì)量保證文檔寫作
8.1軟件質(zhì)量保證定義
8.2軟件質(zhì)量保證管理
8.2.1SQA過程
8.2.2SQA偏差過程
第9章軟件文檔配置管理
9.1軟件配置管理過程
9.1.1軟件配置管理出現(xiàn)的背景
9.1.2軟件配置管理發(fā)展現(xiàn)狀
9.1.3軟件配置管理的目的
9.1.4軟件配置管理的基本活動
9.2配置管理過程規(guī)范
9.2.1配置管理計劃
9.2.2實施配置管理
9.3配置管理工具
9.4軟件文檔的配置管理方案
9.4.1軟件配置管理環(huán)境的設(shè)置
9.4.2軟件配置管理機制的組成和建立
9.4.3軟件配置管理活動的實施流程
9.4.4軟件配置管理基本任務(wù)的相關(guān)規(guī)范
9.4.5配置管理的標(biāo)識規(guī)范
9.4.6配置管理的建議
9.5需求文檔變更的管理
9.5.1需求變更的原因
9.5.2需求變更的處理流程
第10章企業(yè)軟件文檔的管理
10.1企業(yè)軟件文檔分類
10.2企業(yè)軟件文檔管理要求
10.3企業(yè)軟件文檔管理流程
10.4項目文檔的管理
附錄A文檔封面模板
附錄B項目規(guī)劃期文檔模板
B.1可行性研究報告模板
B.2項目方案書模板
附錄C需求類文檔模板
C.1需求調(diào)研報告
C.2需求規(guī)格說明書
C.3用例使用場景模版與實例
C.4用例描述模板
C.5需求評審報告
C.6需求分析報告檢查表
附錄D文檔設(shè)計模板
D.1軟件架構(gòu)設(shè)計說明書
D.2概要設(shè)計說明書
D.2.1模板1
D.2.2模板2
D.3詳細設(shè)計說明書
D.3.1模板1
D.3.2模板2
D.4數(shù)據(jù)庫設(shè)計說明書
附錄E設(shè)計文檔模板
E.1軟件配置管理規(guī)范
E.2軟件修改報告
附錄F單元測試報告文檔模板
附錄G項目管理文檔模板
G.1風(fēng)險列表
G.2周報
附錄H質(zhì)量保證文檔模板
H.1質(zhì)量保證計劃
H.2SQA匯總報告
H.3SQA每周報告
H.4SQA偏差報告
附錄I軟件文檔評分標(biāo)準(zhǔn)
參考文獻
第3章需求類文檔寫作
3.1需求概述
作為技術(shù)人員，大家更多關(guān)注的是技術(shù)，但軟件需求在很大程度上決定了軟件是否正確，需求確定后不管如何實現(xiàn)，功能和質(zhì)量給客戶直接帶來的價值遠遠比技術(shù)直接帶來的價值要高。因此，做正確的事比正確地做事更重要。錯誤需求帶來的問題一直是各個軟件公司項目失敗的首要原因，因為獲得需求是個復(fù)雜的過程，要在實踐中不斷地學(xué)習(xí)，提高需求分析的能力。需求有以下三個層次。
1. 業(yè)務(wù)需求
描述客戶的高層次目標(biāo)，通常問題定義本身就是業(yè)務(wù)需求的表征。這種目標(biāo)通常體現(xiàn)在兩個方面。
（1） 問題： 解決企業(yè)/組織運作過程中遇到的問題，如設(shè)備管理混亂、用戶投訴量大、客戶流失率高等。
（2） 機遇： 抓住外部環(huán)境變化所帶來的機會，以便為企業(yè)帶來新的發(fā)展，例如電子商務(wù)、網(wǎng)上銀行、物聯(lián)網(wǎng)等。
業(yè)務(wù)需求就是系統(tǒng)目標(biāo)，它是以業(yè)務(wù)為導(dǎo)向、指導(dǎo)軟件開發(fā)的高層次需求。這類需求通常來自高層，例如項目投資人、購買產(chǎn)品的客戶、實際用戶、市場營銷部門或產(chǎn)品策劃部門。業(yè)務(wù)需求從總體上描述了為什么要開發(fā)系統(tǒng)（why），組織希望達到什么目標(biāo)，一般在可行性研究報告中反映，也可使用前景和范圍（vision and scope）文檔來記錄業(yè)務(wù)需求，這份文檔有時也被稱做項目章程（Project Charter）或市場需求（Market Requirement）文檔。組織愿景是一個組織對將使用的軟件系統(tǒng)所要達成的目標(biāo)的預(yù)期期望，如“希望實施CRM后公司的客戶滿意度達到90％以上”就是一條組織愿景。
2. 用戶需求
用戶需求是指用戶要使用產(chǎn)品完成什么任務(wù)，通常是在問題定義的基礎(chǔ)上進行用戶訪談、調(diào)查，對用戶使用的場景進行整理，從而獲得來自用戶角度的需求。用戶需求必須能夠體現(xiàn)軟件系統(tǒng)將給用戶帶來的業(yè)務(wù)價值，或用戶要求系統(tǒng)必須完成的任務(wù)，也就是說用戶需求描述了用戶能使用系統(tǒng)來做些什么（what），這個層次的需求是非常重要的。
作為需求捕獲階段的主要產(chǎn)物，用戶需求主要具有以下特點：
（1） 零散。用戶會提出不同角度、不同層面、不同粒度的需求，而且常常是以一句話形式提出的，如通過電話、短信等非正式方式提出的需求。
（2） 相互矛盾。由于不同用戶處于企業(yè)/組織的不同層面，可能會出現(xiàn)盲人摸象的情況，導(dǎo)致需求的片面性。
因此，還需要對原始需求進行分析和整理，從而得出更加精確的需求說明。用例是表達用戶需求的一種有效途徑。
3. 軟件需求
由于用戶需求具有零散、片面的特點，因此需求分析人員還需要對其進行分析、提煉、整理，從而生成可指導(dǎo)開發(fā)的、更準(zhǔn)確的軟件需求，軟件需求是需求分析與建模的產(chǎn)物。
軟件需求是需求的主體，它是設(shè)計具體解決方案的依據(jù)（how），其數(shù)量往往比用戶需求高一個數(shù)量級。這些需求記錄在軟件需求規(guī)格說明（Software Requirements Specification，SRS）中。SRS完整地描述了軟件系統(tǒng)的預(yù)期特性，SRS一般被當(dāng)作文檔保存，設(shè)計、實現(xiàn)、測試、質(zhì)量保證、項目管理以及其他相關(guān)的項目過程都要用到SRS。
3.2軟件需求的分類
軟件需求可分為功能需求、質(zhì)量需求、約束條件三種類型，質(zhì)量需求和約束條件也叫非功能需求。
1. 功能需求
功能需求規(guī)定必須在產(chǎn)品中實現(xiàn)的軟件功能，用戶利用這些功能來完成任務(wù)，滿足業(yè)務(wù)需求。
對于功能需求而言，最關(guān)鍵的是如何對其進行組織，否則一句話的描述就會十分分散，很難保證開發(fā)人員逐一理解和滿足這些要求。
在傳統(tǒng)的方法論中，會以系統(tǒng)→子系統(tǒng)→模塊→子模塊的層次結(jié)構(gòu)來組織，和程序的結(jié)構(gòu)相對應(yīng)，但這樣會割裂用戶的使用場景。為了解決這個問題，現(xiàn)代需求理論更加強調(diào)需求分析人員從用戶的角度將系統(tǒng)理解成一個黑盒子，從橫向的使用視角來整理需求。
2. 質(zhì)量需求
質(zhì)量需求不同于產(chǎn)品的功能描述，它從不同方面描述產(chǎn)品的各種特性。這些特性包括可用性、可移植性、性能、安全等，它們對用戶或開發(fā)人員都很重要。
質(zhì)量需求描述有兩個常見問題。
（1） 信息傳遞的無效性： 在很多需求規(guī)格說明書中，會通過一個名為性能需求的小節(jié)來說明非功能需求，列出諸如高可靠性、高可用性、高擴展性等要求。但是很多開發(fā)人員根本就不看這些內(nèi)容，因為這樣的定性描述缺乏判斷標(biāo)準(zhǔn)，故這種信息傳遞方法是無效的。
（2） 忽略了質(zhì)量需求的局部性： 經(jīng)常會看到諸如“所有的查詢響應(yīng)時間都應(yīng)該小于10s”的描述，但是當(dāng)用戶查詢的是年度統(tǒng)計數(shù)據(jù)時，這樣的需求是較難實現(xiàn)的，因此開發(fā)人員就會忽略和不理會這樣的需求，最終的結(jié)果就是導(dǎo)致它成為了擺設(shè)。因此更科學(xué)的做法是利用具體的應(yīng)用場景來描述。
……
新書資訊