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