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