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

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

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

中圖分類號：G642.0 文獻標識碼：B

文章編號：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 前言

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

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

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

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

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

軟件文檔標準 要求學(xué)生了解軟件工程標準化

概念，了解軟件工程標準編制的層次，了解中國的軟件標準，了解ISO9000、CMM國際標準。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5 結(jié)語

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

參考文獻

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

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