面向案例驅動的軟件文檔撰寫能力培養研究

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

摘 要 為了改善軟件專業學生重編程輕文檔的現狀，采用面向案例驅動的軟件文檔撰寫教學方法。通過系統的軟件文檔寫作實踐，培養學生撰寫用戶文檔、開發文檔和管理文檔的技能，鍛煉學生編制、管理和維護軟件文檔的能力，同時也為提高學生的畢業論文撰寫水平奠定基礎。

關鍵詞 軟件文檔寫作；案例驅動；畢業論文

中圖分類號：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 前言

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

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

2 軟件文檔寫作教學內容

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

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

軟件文檔標準 要求學生了解軟件工程標準化

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

軟件文檔表達 要求學生了解軟件文檔的表達載體和涉眾，理解軟件文檔編制的規則，理解軟件文檔編制的質量要求。

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

軟件開發文檔 要求學生了解軟件開發文檔編制的內容，掌握主要軟件文檔的撰寫，理解編碼規約，掌握測試用例的設計方法。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4 面向案例驅動的軟件文檔寫作學習效果

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

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

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

開展規范訓練 結合國際和國內的軟件文檔撰寫規范，對學生進行規范化訓練，使學生熟悉軟件開發各階段文檔撰寫需要遵從的標準和要求。

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

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

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

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

5 結語

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

參考文獻

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

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