面向案例驅(qū)動(dòng)的軟件文檔撰寫能力培養(yǎng)研究

劉海燕+王曉池+張立杰+陶永鵬

摘 要 為了改善軟件專業(yè)學(xué)生重編程輕文檔的現(xiàn)狀，采用面向案例驅(qū)動(dòng)的軟件文檔撰寫教學(xué)方法。通過(guò)系統(tǒng)的軟件文檔寫作實(shí)踐，培養(yǎng)學(xué)生撰寫用戶文檔、開發(fā)文檔和管理文檔的技能，鍛煉學(xué)生編制、管理和維護(hù)軟件文檔的能力，同時(shí)也為提高學(xué)生的畢業(yè)論文撰寫水平奠定基礎(chǔ)。

關(guān)鍵詞 軟件文檔寫作；案例驅(qū)動(dòng)；畢業(yè)論文

中圖分類號(hào)：G642.0 文獻(xiàn)標(biāo)識(shí)碼：B

文章編號(hào)：1671-489X（2017）18-0092-03

Research on Case-Driven Software Document Writing Ability Training//LIU Haiyan， WANG Xiaochi， ZHANG Lijie， TAO Yong-peng

Abstract In order to improve the current situation of emphasizing programming and despising documents for software majors stu-dents， the case-driven teaching method is adopted in the practice of software document writing. Through the system practice of software document writing， improve students skills to write user documents， development documents and management documents. Train the abi-

lity of students to develop， manage and maintain software docu-ments. At the same time， lay the foundation for improving the gra-duation thesis writing level of students.

Key words software document writing； case-driven； graduation thesis

1 前言

計(jì)算機(jī)軟件由程序、數(shù)據(jù)和文檔組成，文檔是計(jì)算機(jī)軟件產(chǎn)品的重要組成部分。文檔記錄目標(biāo)系統(tǒng)各個(gè)階段的設(shè)計(jì)思想和研究成果，不僅是項(xiàng)目管理的依據(jù)、技術(shù)交流的語(yǔ)言、軟件質(zhì)量的保證、人員培訓(xùn)的資料、軟件維護(hù)的支持、軟件歷史的記載和檔案，而且在開發(fā)人員、維護(hù)人員、管理人員、用戶與計(jì)算機(jī)之間起到橋梁作用[1]。如果無(wú)開發(fā)計(jì)劃、無(wú)文檔地直接面對(duì)計(jì)算機(jī)編程，軟件開發(fā)過(guò)程中的可見度很低，就會(huì)導(dǎo)致軟件開發(fā)周期加長(zhǎng)，開發(fā)和維護(hù)成本提高，軟件質(zhì)量得不到保障。因此，近年來(lái)越來(lái)越多的軟件企業(yè)意識(shí)到軟件文檔撰寫的重要性。

軟件專業(yè)的學(xué)生需要了解軟件文檔在軟件開發(fā)過(guò)程中的作用，了解各種文檔編制規(guī)范，熟悉軟件文檔的編寫方法，能夠根據(jù)項(xiàng)目要求，初步具備按照國(guó)家標(biāo)準(zhǔn)和國(guó)際規(guī)范撰寫軟件生命周期各階段文檔的能力。

2 軟件文檔寫作教學(xué)內(nèi)容

軟件文檔寫作課程主要介紹軟件文檔的基本概念、標(biāo)準(zhǔn)、表達(dá)、要求和管理維護(hù)，以及開發(fā)文檔、管理文檔和用戶文檔的撰寫內(nèi)容和方法，主要教學(xué)內(nèi)容如表1所示。各個(gè)章節(jié)主要的學(xué)習(xí)要求簡(jiǎn)述如下。

軟件文檔概述 要求學(xué)生了解軟件文檔的概念，理解軟件文檔的作用，了解軟件文檔的分類，了解軟件文檔與使用者以及軟件文檔編制與軟件生命周期的關(guān)系。

軟件文檔標(biāo)準(zhǔn) 要求學(xué)生了解軟件工程標(biāo)準(zhǔn)化

概念，了解軟件工程標(biāo)準(zhǔn)編制的層次，了解中國(guó)的軟件標(biāo)準(zhǔn)，了解ISO9000、CMM國(guó)際標(biāo)準(zhǔn)。

軟件文檔表達(dá) 要求學(xué)生了解軟件文檔的表達(dá)載體和涉眾，理解軟件文檔編制的規(guī)則，理解軟件文檔編制的質(zhì)量要求。

軟件文檔寫作要求 要求學(xué)生了解軟件編檔的靈活性，掌握如何制訂軟件文檔計(jì)劃，理解軟件編檔步驟，熟悉建立軟件編檔規(guī)程。

軟件開發(fā)文檔 要求學(xué)生了解軟件開發(fā)文檔編制的內(nèi)容，掌握主要軟件文檔的撰寫，理解編碼規(guī)約，掌握測(cè)試用例的設(shè)計(jì)方法。

軟件管理文檔 要求學(xué)生了解常用管理文檔，了解項(xiàng)目開發(fā)計(jì)劃的制訂，掌握文檔評(píng)審結(jié)果和測(cè)試結(jié)果的記錄方法，掌握開發(fā)進(jìn)度報(bào)告和周報(bào)的撰寫，掌握軟件配置管理的主要內(nèi)容，了解項(xiàng)目風(fēng)險(xiǎn)的標(biāo)識(shí)，了解項(xiàng)目開發(fā)總結(jié)報(bào)告的編制。

軟件用戶文檔 要求學(xué)生了解編制軟件用戶文檔的基本要求，掌握軟件用戶使用說(shuō)明文檔的編制。

軟件文檔管理 要求學(xué)生了解軟件文檔的管理和維護(hù)方法，了解軟件文檔管理的常用工具。

3 面向案例驅(qū)動(dòng)的軟件文檔寫作實(shí)踐

面向案例驅(qū)動(dòng)的教學(xué)方法采用“講授+案例分析+答疑+實(shí)踐+考核”的教學(xué)模式。講授階段以教師講授基礎(chǔ)知識(shí)和方法為主；案例分析階段師生一起分析和討論，集思廣益、開闊思路；答疑階段由教師解答學(xué)生在學(xué)習(xí)過(guò)程中遇到的各種疑問(wèn)；實(shí)踐階段由學(xué)生自主撰寫軟件文檔；考核階段包括平時(shí)成績(jī)、大作業(yè)等[2]。采用面向案例驅(qū)動(dòng)的教學(xué)模式，主要教學(xué)實(shí)踐環(huán)節(jié)如下。

學(xué)生組建團(tuán)隊(duì) 學(xué)生以小組為單位進(jìn)行文檔開發(fā)，鼓勵(lì)班級(jí)內(nèi)自由組建團(tuán)隊(duì)，提倡團(tuán)隊(duì)個(gè)性命名、人員合理

搭配；每組2～3人，設(shè)組長(zhǎng)一名，負(fù)責(zé)組織、分工、安排進(jìn)度等。團(tuán)隊(duì)成員不能太多，以免部分成員參與度過(guò)低，形成寄生和依賴；要求團(tuán)隊(duì)成員至少有兩人組成，不鼓勵(lì)單干，單打獨(dú)斗的方式反而會(huì)因此失去團(tuán)隊(duì)協(xié)作能力的鍛煉機(jī)會(huì)。

選定系統(tǒng)主題 各個(gè)小組討論并選定一個(gè)內(nèi)容健康、積極向上、團(tuán)隊(duì)成員感興趣或者前期有所積累的系統(tǒng)主題，如海淘、電影、旅行、體育、明星、家政、換物、外語(yǔ)學(xué)習(xí)、星座、美食、游戲、美妝、訂票、留學(xué)、博客、考試、交友、寵物、環(huán)保、音樂(lè)、保健、飲品、醫(yī)療、圖書、裝修、人力資源、文化推廣、物流、家居、飾品、招聘、養(yǎng)生、攝影等。endprint

確定團(tuán)隊(duì)題目 各小組圍繞選定的系統(tǒng)主題，確定一個(gè)最終的系統(tǒng)題目，如金生銀世珠寶網(wǎng)站、一見鐘情交友平臺(tái)、瀟灑走一回旅游網(wǎng)站、康泰無(wú)憂體檢系統(tǒng)、一生追隨明星網(wǎng)站、幸福味道訂餐網(wǎng)站、說(shuō)走就走旅行網(wǎng)站、一起歹吧美食網(wǎng)站、衣網(wǎng)打盡女裝網(wǎng)站、娛樂(lè)大爆炸綜藝匯總網(wǎng)站、天使之誠(chéng)醫(yī)療系統(tǒng)、Warm Heart愛心交易平臺(tái)、隨心所欲購(gòu)物網(wǎng)站、匠心獨(dú)韻創(chuàng)意品銷售網(wǎng)站、鴻儒專屬購(gòu)書網(wǎng)站、浪漫滿屋飲品網(wǎng)站、時(shí)光剪影攝影網(wǎng)站、諾丁山婚禮策劃網(wǎng)站、靈魂歌者音樂(lè)網(wǎng)站、一路有你交通網(wǎng)站、儲(chǔ)留箱倉(cāng)庫(kù)管理系統(tǒng)、妙手仁心在線問(wèn)醫(yī)網(wǎng)站、洋貨

碼頭海外代購(gòu)網(wǎng)站、Beauty美妝推介網(wǎng)站、鮮果時(shí)光水果網(wǎng)站等。

協(xié)作開發(fā)文檔 教師按照軟件項(xiàng)目開發(fā)的生命周期過(guò)程，分階段講授軟件文檔撰寫所需要的知識(shí)和技能，展示若干案例后，各小組以團(tuán)隊(duì)協(xié)作的方式，按部就班地獨(dú)立撰寫相應(yīng)階段的軟件文檔。全部撰寫的文檔包括《項(xiàng)目進(jìn)度計(jì)劃》《風(fēng)險(xiǎn)管理計(jì)劃》《配置管理計(jì)劃》《軟件測(cè)試計(jì)劃》《進(jìn)度管理表》《可行性研究報(bào)告》《需求分析規(guī)格說(shuō)明書》《概要設(shè)計(jì)說(shuō)明書》《詳細(xì)設(shè)計(jì)式樣書》《測(cè)試用例式樣書》《測(cè)試報(bào)告》《用戶使用說(shuō)明書》《評(píng)審記錄表》《Q&A一覽表》《Bug一覽表》《變更管理表》等。這些文檔都要求以文件夾的方式分門別類進(jìn)行存放和提交，電子版大作業(yè)的參考目錄結(jié)構(gòu)如圖1所示。

進(jìn)行綜合考核 采用多角度、多樣化的考核方式，盡量為每位學(xué)生的付出和努力給出客觀評(píng)價(jià)。除了記錄學(xué)生平時(shí)出勤情況、聽課熱情度、開發(fā)文檔的投入和專注程度，還通過(guò)文檔撰寫方式、完成作品質(zhì)量和問(wèn)題答辯表現(xiàn)等方面，多方位地鑒定學(xué)生開發(fā)文檔的水平和能力；同時(shí)明確要求每個(gè)團(tuán)隊(duì)詳細(xì)描述每位成員具體的任務(wù)承擔(dān)內(nèi)容，以及所做貢獻(xiàn)的比例。從文檔撰寫任務(wù)開始就引導(dǎo)學(xué)生注意自己在團(tuán)隊(duì)中的個(gè)人定位，督促學(xué)生在共同完成奮斗目標(biāo)的過(guò)程中，要學(xué)習(xí)如何在團(tuán)隊(duì)中做出應(yīng)有的貢獻(xiàn)，以及如何得到團(tuán)隊(duì)其他成員的認(rèn)可。

通過(guò)案例驅(qū)動(dòng)的教學(xué)方式，理論結(jié)合實(shí)際，使軟件文檔寫作的教學(xué)由枯燥難懂變得生動(dòng)形象，將軟件文檔具體地呈現(xiàn)給學(xué)生，使學(xué)生在學(xué)習(xí)過(guò)程中真正從軟件定義、分析、設(shè)計(jì)、實(shí)現(xiàn)等角度考慮問(wèn)題，從而對(duì)軟件文檔的寫作有一個(gè)更直觀的認(rèn)識(shí)，促進(jìn)學(xué)生主動(dòng)深入地進(jìn)行探究學(xué)習(xí)。

在軟件文檔寫作實(shí)踐過(guò)程中，為了提高學(xué)生的學(xué)習(xí)質(zhì)量，除了及時(shí)給學(xué)生提供必要的幫助，還著重加入成果演示、文檔評(píng)審和配置管理的實(shí)踐環(huán)節(jié)。

1）成果演示。專門設(shè)立優(yōu)秀作品演示和學(xué)習(xí)環(huán)節(jié)，由文檔作者展示創(chuàng)新成果，分享開發(fā)經(jīng)驗(yàn)和心得，在學(xué)生中起到很好的激勵(lì)和表率作用。對(duì)主動(dòng)演示的團(tuán)隊(duì)的平時(shí)成績(jī)給予加分，成果突出的個(gè)人和團(tuán)隊(duì)在最終的考試成績(jī)中都有相應(yīng)獎(jiǎng)勵(lì)。團(tuán)隊(duì)之間交流、借鑒和比拼的氛圍，在一定程度上激發(fā)了學(xué)生的投入熱情和創(chuàng)新動(dòng)力。

2）文檔評(píng)審。團(tuán)隊(duì)成員分工協(xié)作完成的每一個(gè)開發(fā)文檔、管理文檔和用戶文檔，要求必須在團(tuán)隊(duì)內(nèi)部成員之間進(jìn)行文檔評(píng)審，并且詳細(xì)記錄評(píng)審活動(dòng)的細(xì)節(jié)。如問(wèn)題描述、發(fā)現(xiàn)時(shí)間、發(fā)現(xiàn)者、問(wèn)題原因、問(wèn)題對(duì)策、修改者、修改時(shí)間、確認(rèn)人等信息。有效督促學(xué)生養(yǎng)成對(duì)自己所經(jīng)手的任何成果物都認(rèn)真進(jìn)行復(fù)查的好習(xí)慣，為以后的職業(yè)生涯培養(yǎng)良好的工作素養(yǎng)。

3）配置管理。學(xué)生在開發(fā)軟件文檔的過(guò)程中，不可避免地會(huì)多次修改文檔，需要做好文檔最新版本的備份，以及團(tuán)隊(duì)成員個(gè)人成果的匯總，并且保持文檔的一致性。為此專門教會(huì)學(xué)生使用現(xiàn)成的配置管理工具，將團(tuán)隊(duì)的所有工作成果納入基線庫(kù)，進(jìn)行統(tǒng)一管理。這樣一來(lái)，學(xué)生不但在實(shí)踐層面上熟悉了配置管理的相關(guān)知識(shí)和做法，而且保障了辛苦撰寫的各類文檔都能很好地保存、備份和更新版本，一舉多得。

4 面向案例驅(qū)動(dòng)的軟件文檔寫作學(xué)習(xí)效果

在軟件文檔開發(fā)實(shí)踐過(guò)程中，面向案例驅(qū)動(dòng)的教學(xué)方法幫助學(xué)生逐步掌握常用軟件文檔的寫作方法和技巧，提高學(xué)生的主動(dòng)參與意識(shí)，培養(yǎng)學(xué)生的分析、寫作、表達(dá)、創(chuàng)新以及團(tuán)隊(duì)協(xié)作的能力，學(xué)習(xí)效果主要體現(xiàn)在以下幾個(gè)方面。

強(qiáng)化實(shí)踐操作 開發(fā)軟件文檔案例，采用講授法與案例教學(xué)相結(jié)合的方式，使學(xué)生積極地參與軟件文檔寫作過(guò)程，強(qiáng)化實(shí)踐動(dòng)手能力。

培養(yǎng)外語(yǔ)能力 軟件文檔寫作除了使用漢語(yǔ)，還涉及日語(yǔ)、英語(yǔ)文檔的撰寫，借此提高學(xué)生的IT外語(yǔ)運(yùn)用能力，學(xué)會(huì)如何使用專業(yè)外語(yǔ)撰寫軟件文檔。

開展規(guī)范訓(xùn)練 結(jié)合國(guó)際和國(guó)內(nèi)的軟件文檔撰寫規(guī)范，對(duì)學(xué)生進(jìn)行規(guī)范化訓(xùn)練，使學(xué)生熟悉軟件開發(fā)各階段文檔撰寫需要遵從的標(biāo)準(zhǔn)和要求。

體驗(yàn)崗位角色 通過(guò)面向案例的軟件文檔撰寫，學(xué)生能體驗(yàn)到項(xiàng)目經(jīng)理、質(zhì)量管理員、配置管理員、設(shè)計(jì)人員、程序員、測(cè)試人員、用戶等多種崗位角色，為以后的就業(yè)積累下一定的經(jīng)驗(yàn)。

奠定行業(yè)知識(shí) 學(xué)生涉獵不同行業(yè)的軟件文檔，也能學(xué)習(xí)到一些金融、物流、教育、醫(yī)療等行業(yè)基本的背景知識(shí)，以便日后更好地理解業(yè)務(wù)層面的用戶需求，工作起來(lái)更得心應(yīng)手。

助力畢業(yè)設(shè)計(jì) 撰寫軟件文檔的過(guò)程就是學(xué)習(xí)查閱資料、獲取信息、閱讀文獻(xiàn)、分析問(wèn)題、設(shè)計(jì)規(guī)劃、歸納總結(jié)、認(rèn)真整理的過(guò)程，使得學(xué)生在撰寫畢業(yè)論文時(shí)輕車熟路、游刃有余。

提高綜合素質(zhì) 學(xué)生在軟件文檔開發(fā)過(guò)程中，通過(guò)查閱資料，培養(yǎng)獲取信息和快速領(lǐng)悟的能力；通過(guò)撰寫文檔，鍛煉創(chuàng)新和解決問(wèn)題的能力；通過(guò)文檔演示，完善邏輯思維和語(yǔ)言表達(dá)能力；通過(guò)團(tuán)隊(duì)協(xié)作方式完成作業(yè)，加強(qiáng)責(zé)任意識(shí)和溝通能力，從而提高綜合素質(zhì)。

5 結(jié)語(yǔ)

借助于面向案例驅(qū)動(dòng)的軟件文檔寫作教學(xué)方法，通過(guò)系統(tǒng)的軟件文檔撰寫實(shí)踐，對(duì)學(xué)生普及軟件文檔的基本概念、標(biāo)準(zhǔn)、表達(dá)和要求；使學(xué)生掌握軟件文檔的管理和維護(hù)方法；幫助學(xué)生體驗(yàn)用戶文檔、開發(fā)文檔和管理文檔的系統(tǒng)撰寫；使學(xué)生能夠在理解業(yè)務(wù)的基礎(chǔ)上，高質(zhì)量地使用、編制、管理和維護(hù)軟件文檔，特別是提高學(xué)生對(duì)設(shè)計(jì)式樣書的閱讀理解能力，以及對(duì)常用軟件文檔的撰寫能力。

參考文獻(xiàn)

[1]肖剛，古輝，程振波，等.實(shí)用軟件文檔寫作[M].北京：清華大學(xué)出版社，2005.

[2]施慶平.面向案例驅(qū)動(dòng)的《軟件文檔寫作》課程改革與實(shí)踐[J].現(xiàn)代計(jì)算機(jī)，2013（21）：46-47.endprint