軟件文檔寫作14-用戶文檔

1、1 用戶文檔是軟件開發(fā)人員為軟件用戶了解、使用、操作和維護(hù)等提供的詳用戶文檔是軟件開發(fā)人員為軟件用戶了解、使用、操作和維護(hù)等提供的詳細(xì)資料。用戶文檔包括用戶手冊(cè)、操作手冊(cè)和維護(hù)修改建議等。細(xì)資料。用戶文檔包括用戶手冊(cè)、操作手冊(cè)和維護(hù)修改建議等。8.1 8.1 編制用戶文檔的基本要求編制用戶文檔的基本要求1. 1. 描述規(guī)范準(zhǔn)確描述規(guī)范準(zhǔn)確 用戶文檔的閱讀對(duì)象通常是非計(jì)算機(jī)專業(yè)的人員，因此對(duì)用戶有很強(qiáng)的實(shí)用戶文檔的閱讀對(duì)象通常是非計(jì)算機(jī)專業(yè)的人員，因此對(duì)用戶有很強(qiáng)的實(shí)用和指導(dǎo)意義。要求在描述內(nèi)容、說明方法、提出見解時(shí)都應(yīng)準(zhǔn)確無誤，恰如用和指導(dǎo)意義。要求在描述內(nèi)容、說明方法、提出見解時(shí)都應(yīng)準(zhǔn)確無誤

2、，恰如其分。文檔需要反映哪些內(nèi)容、如何描述、口氣、分寸等，都應(yīng)與編制目的、其分。文檔需要反映哪些內(nèi)容、如何描述、口氣、分寸等，都應(yīng)與編制目的、使用對(duì)象協(xié)調(diào)一致。用詞應(yīng)標(biāo)準(zhǔn)、統(tǒng)一、規(guī)范。使用對(duì)象協(xié)調(diào)一致。用詞應(yīng)標(biāo)準(zhǔn)、統(tǒng)一、規(guī)范。2. 2. 敘述簡練生動(dòng)敘述簡練生動(dòng) 用戶文檔應(yīng)簡潔、精煉，少用用戶難懂的專業(yè)術(shù)語，并力求形象生動(dòng)、圖用戶文檔應(yīng)簡潔、精煉，少用用戶難懂的專業(yè)術(shù)語，并力求形象生動(dòng)、圖文并茂，便于用戶學(xué)習(xí)、理解和掌握軟件的使用、操作。文并茂，便于用戶學(xué)習(xí)、理解和掌握軟件的使用、操作。3. 3. 語言嚴(yán)密平實(shí)語言嚴(yán)密平實(shí) 用戶文檔的價(jià)值在于科學(xué)性。文字表達(dá)必須合乎邏輯，才能有助于用戶使用戶文

3、檔的價(jià)值在于科學(xué)性。文字表達(dá)必須合乎邏輯，才能有助于用戶使用、操作軟件。用、操作軟件。4. 4. 內(nèi)容系統(tǒng)完整內(nèi)容系統(tǒng)完整 用戶文檔作為軟件系統(tǒng)開發(fā)者和用戶之間的界面，應(yīng)能提供給用戶關(guān)于軟用戶文檔作為軟件系統(tǒng)開發(fā)者和用戶之間的界面，應(yīng)能提供給用戶關(guān)于軟件整體結(jié)構(gòu)、功能、安裝、運(yùn)行和操作的有關(guān)知識(shí)，并且用戶文檔的內(nèi)容組織件整體結(jié)構(gòu)、功能、安裝、運(yùn)行和操作的有關(guān)知識(shí)，并且用戶文檔的內(nèi)容組織應(yīng)該有系統(tǒng)性、層次性，使之成為軟件使用、操作的清晰的應(yīng)該有系統(tǒng)性、層次性，使之成為軟件使用、操作的清晰的“交通圖交通圖”。28.2 8.2 軟件常用表示形式軟件常用表示形式 軟件的表示方法為軟件系統(tǒng)建立一個(gè)基本構(gòu)

4、架，對(duì)理解軟件，特別是對(duì)于軟件的表示方法為軟件系統(tǒng)建立一個(gè)基本構(gòu)架，對(duì)理解軟件，特別是對(duì)于軟件的維護(hù)，將是非常重要的。軟件的維護(hù)，將是非常重要的。1. 1. 容器模型容器模型 基于一個(gè)共享數(shù)據(jù)庫的系統(tǒng)模型一般稱為容器模型?；谝粋€(gè)共享數(shù)據(jù)庫的系統(tǒng)模型一般稱為容器模型。 如果系統(tǒng)的工作所使用的數(shù)據(jù)是圍繞共享數(shù)據(jù)庫進(jìn)行的，這可以考慮采用如果系統(tǒng)的工作所使用的數(shù)據(jù)是圍繞共享數(shù)據(jù)庫進(jìn)行的，這可以考慮采用容器模型來表達(dá)其系統(tǒng)結(jié)構(gòu)。下圖是一種集成容器模型來表達(dá)其系統(tǒng)結(jié)構(gòu)。下圖是一種集成CASECASE工具集的體系結(jié)構(gòu)。工具集的體系結(jié)構(gòu)。設(shè)計(jì)編輯器設(shè)計(jì)編輯器代碼生成器代碼生成器設(shè)計(jì)分析器設(shè)計(jì)分析器報(bào)告生成器

5、報(bào)告生成器程序編輯器程序編輯器設(shè)計(jì)轉(zhuǎn)換器設(shè)計(jì)轉(zhuǎn)換器項(xiàng)目存儲(chǔ)項(xiàng)目存儲(chǔ) 在上面的例子中，容器是被動(dòng)的，對(duì)它的控制是由其它子系統(tǒng)完成的。在上面的例子中，容器是被動(dòng)的，對(duì)它的控制是由其它子系統(tǒng)完成的。32. 2. 客戶機(jī)客戶機(jī)/ /服務(wù)器模型服務(wù)器模型 這個(gè)模型用于表示一個(gè)分布式系統(tǒng)，說明數(shù)據(jù)和加工過程在多個(gè)處理器這個(gè)模型用于表示一個(gè)分布式系統(tǒng)，說明數(shù)據(jù)和加工過程在多個(gè)處理器之間的分配。其例子如下圖所示。之間的分配。其例子如下圖所示。用戶用戶用戶用戶用戶用戶用戶接口客戶進(jìn)程用戶接口客戶進(jìn)程用戶接口客戶進(jìn)程用戶接口客戶進(jìn)程用戶接口客戶進(jìn)程用戶接口客戶進(jìn)程多媒體數(shù)據(jù)庫服務(wù)器及中間件多媒體數(shù)據(jù)庫服務(wù)器及中間

6、件圖像圖像服務(wù)器服務(wù)器視頻視頻服務(wù)器服務(wù)器聲音聲音服務(wù)器服務(wù)器文本文本服務(wù)器服務(wù)器圖像圖像數(shù)據(jù)庫數(shù)據(jù)庫視頻視頻數(shù)據(jù)庫數(shù)據(jù)庫聲音聲音數(shù)據(jù)庫數(shù)據(jù)庫文本文本數(shù)據(jù)庫數(shù)據(jù)庫43. 3. 抽象機(jī)模型抽象機(jī)模型 抽象機(jī)模型，也稱分層模型，常用來表示子系統(tǒng)的接口模型。抽象機(jī)模型，也稱分層模型，常用來表示子系統(tǒng)的接口模型。 將下圖組織成一系列的層次，每一層次定義一組服務(wù)。一個(gè)著名的例子將下圖組織成一系列的層次，每一層次定義一組服務(wù)。一個(gè)著名的例子是網(wǎng)絡(luò)協(xié)議是網(wǎng)絡(luò)協(xié)議OSIOSI參考模型。參考模型。 4. 4. 接口描述接口描述 大型系統(tǒng)總是分解成獨(dú)立開發(fā)的一些子系統(tǒng)。因此，在軟件描述中的一大型系統(tǒng)總是分解成獨(dú)立

7、開發(fā)的一些子系統(tǒng)。因此，在軟件描述中的一個(gè)必要成分就是定義子系統(tǒng)接口。接口的示意如下圖。個(gè)必要成分就是定義子系統(tǒng)接口。接口的示意如下圖。子系統(tǒng)子系統(tǒng)A子系統(tǒng)子系統(tǒng)B5 接口是一種抽象的概念，在面向?qū)ο蟮某绦蛟O(shè)計(jì)中，可以是一個(gè)類的公接口是一種抽象的概念，在面向?qū)ο蟮某绦蛟O(shè)計(jì)中，可以是一個(gè)類的公開的數(shù)據(jù)成員或成員函數(shù)，也可以是若干個(gè)類抽象出的接口對(duì)象。接口抽象開的數(shù)據(jù)成員或成員函數(shù)，也可以是若干個(gè)類抽象出的接口對(duì)象。接口抽象概念如圖所示。概念如圖所示。Class1- - 用于接口數(shù)據(jù)成員用于接口數(shù)據(jù)成員- - 其它數(shù)據(jù)成員其它數(shù)據(jù)成員Class2+ + 用于接口的成員函數(shù)用于接口的成員函數(shù)()()

8、+ + 其它成員函數(shù)其它成員函數(shù)()()Class3Class4interface接口對(duì)象接口對(duì)象Class5 接口描述主要包括三方面信息：接口描述主要包括三方面信息：- - 類型名類型名：即一組對(duì)象的名字：即一組對(duì)象的名字- - 接口語法接口語法：定義接口操作的名字、參數(shù)個(gè)數(shù)、參數(shù)類型及操作結(jié)果類型：定義接口操作的名字、參數(shù)個(gè)數(shù)、參數(shù)類型及操作結(jié)果類型- - 接口描述接口描述：對(duì)接口操作給出無二義的語法和語義解釋：對(duì)接口操作給出無二義的語法和語義解釋65. 5. 控制模型控制模型 控制模型控制模型在體系結(jié)構(gòu)層次上描述子系統(tǒng)之間的控制流。有兩在體系結(jié)構(gòu)層次上描述子系統(tǒng)之間的控制流。有兩種表示形

9、式：種表示形式：集中式控制集中式控制和和事件驅(qū)動(dòng)控制事件驅(qū)動(dòng)控制。 集中式控制集中式控制模型中，由一個(gè)稱為系統(tǒng)控制器的子系統(tǒng)來負(fù)責(zé)模型中，由一個(gè)稱為系統(tǒng)控制器的子系統(tǒng)來負(fù)責(zé)管理其它子系統(tǒng)的執(zhí)行，模型工具子系統(tǒng)是管理其它子系統(tǒng)的執(zhí)行，模型工具子系統(tǒng)是順序執(zhí)行順序執(zhí)行還是還是并發(fā)執(zhí)并發(fā)執(zhí)行行，而分成，而分成調(diào)用調(diào)用- -返回模型返回模型和和管理者模型管理者模型。 下圖是一個(gè)調(diào)用下圖是一個(gè)調(diào)用- -返回式集中控制模型的結(jié)構(gòu)示例：返回式集中控制模型的結(jié)構(gòu)示例：主程序主程序程序程序1程序程序2程序程序3程序程序1.1程序程序1.2程序程序3.1程序程序3.27 下圖是一種實(shí)時(shí)系統(tǒng)的管理者集中控制模型的結(jié)

10、構(gòu)示例：下圖是一種實(shí)時(shí)系統(tǒng)的管理者集中控制模型的結(jié)構(gòu)示例：故障處理器故障處理器傳感器進(jìn)程傳感器進(jìn)程傳動(dòng)裝置進(jìn)程傳動(dòng)裝置進(jìn)程計(jì)算進(jìn)程計(jì)算進(jìn)程系統(tǒng)控制系統(tǒng)控制用戶界面用戶界面 在基于事件驅(qū)動(dòng)控制模型中，各個(gè)子系統(tǒng)都可以接受來自在基于事件驅(qū)動(dòng)控制模型中，各個(gè)子系統(tǒng)都可以接受來自外部子系統(tǒng)的事件，并對(duì)此作出響應(yīng)。外部子系統(tǒng)的事件，并對(duì)此作出響應(yīng)。 典型的有典型的有廣播型事件驅(qū)動(dòng)控制模型廣播型事件驅(qū)動(dòng)控制模型和和中斷型控制模型中斷型控制模型。8 廣播型事件驅(qū)動(dòng)控制模型的結(jié)構(gòu)示例如圖：廣播型事件驅(qū)動(dòng)控制模型的結(jié)構(gòu)示例如圖：子系統(tǒng)子系統(tǒng)1子系統(tǒng)子系統(tǒng)2子系統(tǒng)子系統(tǒng)3子系統(tǒng)子系統(tǒng)n時(shí)間和消息處理器時(shí)間和消息處

11、理器 中斷驅(qū)動(dòng)型控制模型的結(jié)構(gòu)示例如圖：中斷驅(qū)動(dòng)型控制模型的結(jié)構(gòu)示例如圖：處理器處理器1 1處理器處理器2 2處理器處理器3 3處理器處理器4 4進(jìn)程進(jìn)程1 1進(jìn)程進(jìn)程2 2進(jìn)程進(jìn)程3 3進(jìn)程進(jìn)程4 4中斷向量中斷向量96. 6. 數(shù)據(jù)流模型數(shù)據(jù)流模型 數(shù)據(jù)流模型是描述系統(tǒng)數(shù)據(jù)處理的一種很直觀的方式。下圖是一個(gè)訂單數(shù)據(jù)流模型是描述系統(tǒng)數(shù)據(jù)處理的一種很直觀的方式。下圖是一個(gè)訂單處理的數(shù)據(jù)流圖。處理的數(shù)據(jù)流圖。完成訂完成訂單表單表完成訂完成訂單表單表完成訂完成訂單表單表驗(yàn)證訂單驗(yàn)證訂單記錄訂單記錄訂單訂單明細(xì)訂單明細(xì)+ +空白訂單表空白訂單表訂單文件訂單文件預(yù)算文件預(yù)算文件 下圖是一個(gè)下圖是一個(gè)C

12、ASECASE工具集的工具集的數(shù)據(jù)流圖。數(shù)據(jù)流圖。設(shè)計(jì)設(shè)計(jì)編輯器編輯器設(shè)計(jì)交叉設(shè)計(jì)交叉檢查器檢查器設(shè)計(jì)設(shè)計(jì)分析器分析器報(bào)告報(bào)告生成器生成器代碼框架代碼框架生成器生成器設(shè)計(jì)設(shè)計(jì)數(shù)據(jù)庫數(shù)據(jù)庫設(shè)計(jì)設(shè)計(jì)數(shù)據(jù)庫數(shù)據(jù)庫檢查過檢查過的設(shè)計(jì)的設(shè)計(jì)引用的引用的設(shè)計(jì)設(shè)計(jì)輸出輸出代碼代碼輸入輸入設(shè)計(jì)設(shè)計(jì)有效有效設(shè)計(jì)設(shè)計(jì)設(shè)計(jì)設(shè)計(jì)分析分析用戶用戶報(bào)告報(bào)告檢查過檢查過的設(shè)計(jì)的設(shè)計(jì)107. 7. 狀態(tài)機(jī)模型狀態(tài)機(jī)模型 狀態(tài)機(jī)模型是一種描述系統(tǒng)對(duì)內(nèi)或外部事件響應(yīng)的行為模型，用來表示系狀態(tài)機(jī)模型是一種描述系統(tǒng)對(duì)內(nèi)或外部事件響應(yīng)的行為模型，用來表示系統(tǒng)狀態(tài)和事件，以及事件引發(fā)系統(tǒng)在狀態(tài)之間的轉(zhuǎn)換。下圖是一個(gè)簡單微波爐統(tǒng)狀態(tài)和事件

13、，以及事件引發(fā)系統(tǒng)在狀態(tài)之間的轉(zhuǎn)換。下圖是一個(gè)簡單微波爐的狀態(tài)機(jī)模型示例。的狀態(tài)機(jī)模型示例。全功率全功率Do: set power=600等待等待Do: displaytime半功率半功率Do: set power=300設(shè)置時(shí)間設(shè)置時(shí)間Do:get numberExit:set time屏蔽屏蔽Do: displayWaiting激活激活Do: displayready等待等待Do: displaytime操作操作Do: operateopen全功率全功率半功率半功率全功率全功率半功率半功率機(jī)時(shí)器機(jī)時(shí)器機(jī)時(shí)器機(jī)時(shí)器門開門開門開門開門關(guān)門關(guān)開始開始取消取消系統(tǒng)出錯(cuò)系統(tǒng)出錯(cuò)數(shù)字?jǐn)?shù)字118. 8.

14、 數(shù)據(jù)模型數(shù)據(jù)模型 絕大多數(shù)的軟件系統(tǒng)都要使用數(shù)據(jù)庫，因此，系統(tǒng)建模的一項(xiàng)重要工作絕大多數(shù)的軟件系統(tǒng)都要使用數(shù)據(jù)庫，因此，系統(tǒng)建模的一項(xiàng)重要工作就是定義系統(tǒng)處理的邏輯結(jié)構(gòu)。數(shù)據(jù)模型就是要表達(dá)這樣的一個(gè)結(jié)構(gòu)。就是定義系統(tǒng)處理的邏輯結(jié)構(gòu)。數(shù)據(jù)模型就是要表達(dá)這樣的一個(gè)結(jié)構(gòu)。 數(shù)據(jù)模型可以表示為一個(gè)數(shù)據(jù)模型可以表示為一個(gè)有向圖有向圖，包含一系列不同類型的結(jié)點(diǎn)，結(jié)點(diǎn)之，包含一系列不同類型的結(jié)點(diǎn)，結(jié)點(diǎn)之間的連線表示結(jié)點(diǎn)之間的關(guān)系，每個(gè)結(jié)點(diǎn)有結(jié)點(diǎn)標(biāo)示和若干屬性描述。下圖間的連線表示結(jié)點(diǎn)之間的關(guān)系，每個(gè)結(jié)點(diǎn)有結(jié)點(diǎn)標(biāo)示和若干屬性描述。下圖是一個(gè)由一組結(jié)點(diǎn)和一組關(guān)聯(lián)構(gòu)成的是一個(gè)由一組結(jié)點(diǎn)和一組關(guān)聯(lián)構(gòu)成的ERAER

15、A數(shù)據(jù)模型，表是對(duì)應(yīng)的數(shù)據(jù)字典。數(shù)據(jù)模型，表是對(duì)應(yīng)的數(shù)據(jù)字典。設(shè)計(jì)設(shè)計(jì)NamedescriptionC-dateM-date標(biāo)簽標(biāo)簽Nametexticon鏈接鏈接Nametype鏈接鏈接Nametype有結(jié)有結(jié)點(diǎn)點(diǎn)n1有標(biāo)有標(biāo)簽簽11is an有鏈有鏈接接有標(biāo)有標(biāo)簽簽1nn1有鏈有鏈接接12鏈接鏈接12ERAERA圖所對(duì)應(yīng)的數(shù)據(jù)字典圖所對(duì)應(yīng)的數(shù)據(jù)字典名名 字字描描 述述類類 型型日日 期期has-labels在結(jié)點(diǎn)或關(guān)聯(lián)實(shí)體和類型標(biāo)簽實(shí)體間的在結(jié)點(diǎn)或關(guān)聯(lián)實(shí)體和類型標(biāo)簽實(shí)體間的1:n關(guān)系關(guān)系關(guān)系關(guān)系2005-12-30label存放結(jié)點(diǎn)或關(guān)聯(lián)的結(jié)構(gòu)化的或非結(jié)構(gòu)化的信息。標(biāo)存放結(jié)點(diǎn)或關(guān)聯(lián)的結(jié)構(gòu)化

16、的或非結(jié)構(gòu)化的信息。標(biāo)簽由一個(gè)圖標(biāo)簽由一個(gè)圖標(biāo)(可能是一個(gè)透明方塊可能是一個(gè)透明方塊)和相關(guān)的文本和相關(guān)的文本表示表示實(shí)體實(shí)體2005-12-30link表示設(shè)計(jì)實(shí)體的結(jié)點(diǎn)間的表示設(shè)計(jì)實(shí)體的結(jié)點(diǎn)間的1:1關(guān)系，關(guān)聯(lián)具有類型和關(guān)系，關(guān)聯(lián)具有類型和名字名字關(guān)系關(guān)系2005-12-30name(label)每個(gè)標(biāo)簽具有一個(gè)說明類型的名字，該名字在設(shè)計(jì)每個(gè)標(biāo)簽具有一個(gè)說明類型的名字，該名字在設(shè)計(jì)中的標(biāo)簽類型必須唯一中的標(biāo)簽類型必須唯一屬性屬性2005-12-30name(node)每個(gè)結(jié)點(diǎn)名字在整個(gè)設(shè)計(jì)中必須唯一，名字可以長每個(gè)結(jié)點(diǎn)名字在整個(gè)設(shè)計(jì)中必須唯一，名字可以長達(dá)達(dá)64個(gè)字符個(gè)字符屬性屬性200

17、5-12-309. 9. 對(duì)象模型對(duì)象模型 對(duì)象模型是一種映射真實(shí)世界中實(shí)體及對(duì)其操作的自然方法。對(duì)象模型對(duì)象模型是一種映射真實(shí)世界中實(shí)體及對(duì)其操作的自然方法。對(duì)象模型既可以表達(dá)系統(tǒng)數(shù)據(jù)，又可以表達(dá)對(duì)數(shù)據(jù)的處理。因此，對(duì)象模型可以看作既可以表達(dá)系統(tǒng)數(shù)據(jù)，又可以表達(dá)對(duì)數(shù)據(jù)的處理。因此，對(duì)象模型可以看作是數(shù)據(jù)流模型和數(shù)據(jù)模型的結(jié)合。是數(shù)據(jù)流模型和數(shù)據(jù)模型的結(jié)合。 下面的圖是用下面的圖是用UMLUML描述對(duì)象類的例子。圖中，每個(gè)矩形表示一個(gè)對(duì)象類，描述對(duì)象類的例子。圖中，每個(gè)矩形表示一個(gè)對(duì)象類，其中包括對(duì)象名字、對(duì)象類中的屬性、對(duì)象類的中操作。向上的空三角箭頭其中包括對(duì)象名字、對(duì)象類中的屬性、對(duì)象類

18、的中操作。向上的空三角箭頭表示繼承。表示繼承。13- Catalogue number- Acquisition- Cost- Type- Status- Number of copies+ Acquire()+ Catalogue()+ Dispose()+ Issue()+ Return()- Author- Edition- Publication date- ISBN- Title- Publisher- Title- Medium- Year- Issue- Version- Platform- Director- Date of release- Distributor圖書館系統(tǒng)的部分類層次圖書館系統(tǒng)的部分類層次14 除了通過繼承來組織系統(tǒng)，對(duì)象類還可以由其它的對(duì)象組合而成，稱為除了通過繼承來組織系統(tǒng)，對(duì)象類還可以由其它的對(duì)象組合而成，稱為對(duì)象成員。這種關(guān)系稱為對(duì)象的聚合，使用菱形表示聚合關(guān)系。如圖所示的對(duì)象成員。這種關(guān)系稱為對(duì)象的聚合，使用菱形表示聚合關(guān)系。如圖所示的是課程的聚合對(duì)象表示。是課程的聚合對(duì)象表示。課程課程Course ti