刘海燕+王晓池+张立杰+陶永鹏

摘 要 为了改善软件专业学生重编程轻文档的现状，采用面向案例驱动的软件文档撰写教学方法。通过系统的软件文档写作实践，培养学生撰写用户文档、开发文档和管理文档的技能，锻炼学生编制、管理和维护软件文档的能力，同时也为提高学生的毕业论文撰写水平奠定基础。

关键词 软件文档写作；案例驱动；毕业论文

中图分类号：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