软件文档写作实训

辽 宁 工 业 大 学 软件文档写作 实训报告题目： 班级管理系统软件文档 院（系）: 软件学院 专业班级： 指导教师： 教师职称： 副教授 起止时间： 2012.11.26-2012.12.02 实训任务及评语院（系）：软件学院 教研室：软件教研室学 号实训题目班级管理系统软件文档实训任务实训任务及要求：1、 了解软件开发周期各阶段的文档。2、 掌握各文档阐述的内容及作用。3、 了解文档所采用的国际、国家等相关标准。4、 了解各文档所涉及的软件知识。5、 掌握各文档采用的描述工具。6、 具体编写出2个主要的软件文档。实训过程中，要严格遵守实训的时间安排，听从指导教师的指导。正确地完成上述内容，记录实习日记，规范完整地撰写出实训报告。几个人为一组完成一个相对完整的软件系统开发文档，组内成员编写的文档不能重复，文档要严格按照所采用的标准编写，图表布局要合理规范。指导教师评语及成绩成绩： 指导教师签字： 年 月 日辽 宁 工 业 大 学 综 合 实 训 说 明 书（论 文）目 录第1章 实训目的与要求11.1 实训目的11.2 实训的实验环境11.3 实训的预备知识11.4 实训要求1第2章 软件文档及其组成22.1软件文档的作用及分类22.2软件文档所采用的标准32.3 软件文档的主要内容4第3章 实 例53.1班级管理系统测试设计说明书实例53.2班级管理系统用户手册实例10第4章 实训日记13第5章 实训总结14参考文献15第1章 实训目的与要求1.1 实训目的 本实训要求学生通过具体的实例，模仿软件开发过程中软件文档写作的具体方法和步骤，分组完成一套较为简单软件文档，具体要达到以下几点目的。1、了解软件开发周期各阶段的文档。2、掌握各文档阐述的内容及作用。3、了解文档所采用的国际、国家等相关标准。4、了解各文档所涉及的软件知识。5、掌握各文档采用的描述工具。6、具体编写出2个主要的软件文件。 1.2 实训的实验环境学校图书馆，互联网查询环境，具有软件图表制作软件的计算机。1.3 实训的预备知识要求学生修完全部专科所有课程，具有较全面计算机软件知识和一定的文献检索能力及动手实践能力。该实训应安排在毕业设计之前进行。1.4 实训要求实训过程中，要严格遵守实训的时间安排，听从指导教师的指导。正确地完成上述内容，记录实习日记，规范完整地撰写出实训报告。 第2章 软件文档及其组成2.1软件文档的作用及分类一、软件文档的定义通过网上查阅，我知道了软件文档的定义。软件文档(document)也称文件,通常指的是一些记录的数据和数据媒体，它具有固定不变的形式，可被人和计算机阅读。它和计算机程序共同构成了能完成特定功能的计算机软件(有人把源程序也当作文档的一部分)。我们知道,硬件产品和产品资料在整个生产过程中都是有形可见的,软件生产则有很大不同文档本身就是软件产品。没有文档的软件,不成其为软件,更谈不到软件产品。软件文档的编制(documentation)在软件开发工作中占有突出的地位和相当的工作量。高效率,高质量地开发,分发,管理和维护文档对于转让,变更,修正,扩充和使用文档,对于充分发挥软件产品的效益有着重要意义。二、软件文档的分类软件文档分类：基于软件生存期方法，可以从形式上将软件文档大致分为两类：软件开发过程中需要填写的各种图表，及应编制的各种技术文件或管理资料。而根据其产生和使用的范围，主要划分为三大类：开发文档、用户文档和管理文档。三、软件文档的作用1、开发文档作用:一作为软件生存期夹断之间的通信工具，记录生成软件需求、设计、编码、测试等的详细规定和说明。二描述开发小组的工作职责。通过规定软件规划设计主题脚本编制、文档编制、质量保证等人员的角色，来定义“如何做”和“何时做”。三用作检验点，而允许管理者评估开发进度。如果开发文档缺失或过时，管理者将失去跟踪和控制软件项目的重要工具。四形成系统维护人员所需求的基本的软件支持文档，并构成产品文档的一部分。五记录软件开发的历史。2、用户文档作用：一为使用和运行软件产品的用户提供培训和运行参考信息。二为产品维护工程师提供必要的信息。三促进和方便软件产品的市场推广。3、管理文档作用：主要是对软件开发过程的管理信息进行描述。2.2软件文档所采用的标准标准编号:GB/T 8567-2006标准名称:计算机软件文档编制规范标准状态:现行英文标题:Specification for computer software documentation替代情况:替代GB/T 8567-1988实施日期:2006-7-01颁布部门:中华人民共和国国家质量监督检验检疫总局，中国国家标准化管理委员会内容简介:本标准对软件的开发过程和管理过程应编制的主要文档及其编制的内容、格式规定了基本要求。本标准原则上适用于所有类型的软件产品的开发过程和管理过程。除了国际标准，还可以参照其它工程领域对工程标准划分的方法，软件工程标准主要有两种划分方法：按标准的类型划分和按标准的范围划分。1、按标准的类型划分：按标准的类型划分主要有过程标准、产品标准、行业标准、记法标准等。过程标准与开发一个产品或从事一项服务的一系列活动或操作有关。过程标准使用一组方法、工具和技术，给出“谁来做”、“做什么”、“如何做”、“何时做”、“何地做”及在软件工程活动中进行的不同层次工作的过程模型。产品标准则涉及软件工程事务的格式和内容。软件开发和维护活动文档化的结果就是软件产品，软件文档是软件工程活动进一步开展的基础。软件开发作为一种行业，其行业标准涉及软件工程的所有方面，如职业认证、职业培训、产品许可等。行业标准可以等同于行业行为规范。记法标准规定了在软件工程行业范围内，以唯一的方式进行交流的方法，如术语、表示法、语言等。它其实是一种语境规范。2、按标准的范围划分：按标准的范围划分主要是根据软件的任务功能和软件生存期进行比较、判定、评价和确定软件工程标准的范围和内容。任务功能可以表示软件工程过程，可以划分为产品工程功能、验证与确认功能以及技术管理功能3个部分。产品工程功能包括定义、生产和支持最终产品所必须的过程。验证和确认功能是检查产品质量的活动。技术管理功能是构造和控制产品工程的过程。这3个部分并不集中在单个的软件生存周期里，而是并行进行的生产、检查和控制活动。2.3 软件文档的主要内容在项目开发过程中，应该要去编写好十三种文档，文档编制要求具有针对性、精确性、清晰性、完整性、灵活性和可追溯性。完备的文档对软件的开发及使用起了很大的作用。1、可行性研究报告：说明该软件开发项目的实现在技术上,经济上和社会因素上的可行性,评述为了合理地达到开发目标可供选择的各种可能实施的方案,说明并论证所选定实施方案的理由。 2、 项目开发计划：为软件项目实施方案制定出具体计划,应该包括各部分工作的负责人员,开发的进度,开发经费的预算,所需的硬件及软件资源等。3、软件需求说明书:也称软件规格说明书,其中对所开发软件的功能,性能,用户界面及运行环境等作出详细的说明。它是用户与开发人员双方对软件需求取得共同理解基础上达成的协议, 也是实施开发工作的基础。 4、概要设计说明书:该说明书是概要设计阶段的工作 成果,它应说明功能分配,模块划分,程序的总体结构,输入输出以及接口设计,运行设计,数据结构设计和出错处理设计等,为详细设计奠定基础。 5、详细设计说明书:着重描述每一模块是怎样实现的, 包括实现算法,逻辑流程等。 6、用户操作手册:本手册详细描述软件的功能,性能和用户界面,使用户了解如何使用该软件。 7、测试计划:为做好组装测试和确认测试,需为如何组织测试制定实施计划。计划应包括测试的内容,进度,条件,人员,测试用例的选取原则,测试结果允许的偏差范围等。 8、测试分析报告:测试工作完成以后,应提交测试计划执行 情况的说明。对测试结果加以分析,并提出测试的结论意见。 9、开发进度月报:该月报系软件人员按月向管理部门提交的项目进展情况报告。报告应包括进度计划与实际执行情况的比较, 阶段成果,遇到的问题和解决的办法以及下个月的打算等。 10、项目开发总结报告:软件项目开发完成以后,应与项目实施计划对照,总结实际执行的情况,如进度,成果,资源利用,成本和投入的人力。此外还需对开发工作作出评价,总结出经验和教训。 11、软件维护手册：主要包括软件系统说明、程序模块说明、操作环境、支持软件的说明、维护过程的说明，便于软件的维护。12、软件问题报告：指出软件问题的登记情况，为软件修改提供准备文档。13、软件修改报告：软件产品投入运行以后，发现了需对其进行修正、更改等问题，应将存在的问题、修改的考虑以及修改的影响作出详细的描述，提交审批。第3章 实 例3.1班级管理系统测试设计说明书实例测试计划（GB856788）1引言1.1编写目的任何系统的开发都不可能做到完美，都存在一定的问题和漏洞，有些很明显的表现出来，而有些却很隐蔽，只有不断的检验测试才能发现系统中存在漏洞及不足的地方，并在此基础上总结系统开发过程中所出现的问题和解决的方法，汲取软件开发经验。为系统今后可能出现的更多更深层次的问题的解决提供一定的基础，力求进一步完善创新系统的各项性能。1.2背景本项目是开发完成的班级管理系统，是针对班级用户的需求统计而开发的系统软件，了加强对班级的管理，规范班级工作的监督开展，建立合理的班级体系，培训良好的班级群体，本项目由软件工程11专升本信管专业11级2.3.4班组员提出，后期开发由各组员承担。1.3定义1. CMS：班级管理系统简称2. SQA：Software Quality Assurance3. SCM：Software Configuration Management4. SPP：Software Process Plan5. CMM：Capability Maturity Model6. PM：Project Manager7. UCP：Use Case Point1.4参考资料1. 班级管理系统-用户需求2. Led项目系统测试计划3. 班级管理系统用例模型4. 班级管理系统需求规格说明书2计划2.1软件说明测试需求编号 测试需求项优先级1系统身份验证a2成员相册a3相片管理a4成员资料a5个人资料a6短消息c7班级新闻c8教师通讯录a9班级管理b10安全退出C备注：a. 高软件必须实现的功能，用户有明确的功能定义和要求；b. 中软件应该实现的功能，用户的功能定义和要求可能是模糊的、不具体的、或低约束的，但是这类功能的缺少会导致用户的不满意，因此这类功能的具体需求应当由需求分析人员诱导用户产生并明确；c. 低软件尽量实现的功能，并可根据开发进度进行取舍，但这类功能的实现将会增加用户的满意度。2.2测试内容测试1：名称：系统登录测试目的：测试系统登录界面。进度安排：2012-11-26 内容：用户名、密码、身份输入、合理性检查、合法性检查，系统操作界面显示控制测试 2：名称：用户管理测试。 目的：测试用户管理界面功能。进度安排：2012-11-26 内容：可以添加、删除用户，此界面普通用户没有提升、撤销、删除、锁定、解锁功能。测试 3：名称： 班级相册管理测试。 目的：班级相册管理界面功能。进度安排：2012-11-27 内容：可以对班级相册信息进行添加、修改、删除。 测试 4：名称：班级信息管理测试。 目的：测试班级信息管理界面功能。 进度安排：2012-11-27内容：通过此界面可以对班级信息进行修改，可以对班级实时信息调整。测试 5：名称：班级留言管理测试。 目的：测试班级留言管理界面功能。进度安排：2012-11-28 内容：可以通过此界面在班级里发表留言，管理员和副管理员可以通过删除留言对留言信息进行删除。测试6：名称：短消息管理测试目的：测试短消息管理界面功能。进度安排：2012-11-29 内容：通过此界面可以给其他用户发送短消息或是接受他人给自己发送的短消息。测试 7：名称：班级新闻管理测试 目的：测试班级新闻管理界面功能。进度安排：2012-11-29 内容：通过此界面可以查看班级新闻，只有管理员和副管理员可以对班级新闻进行添加、修改、删除，普通用户则没有使用的权限。测试 8：名称： 教师通讯录管理测试。 目的：测试教师通讯录管理界面功能。进度安排：2012-11-30 内容：通过此界面每个用户都可以查看教师的信息，只有管理员和副管理员可以对教师通讯录进行添加、修改、删除，普通用户则没有使用的权限。测试 9：名称：个人资料信息管理测试。 目的：测试个人资料信息管理界面功能。 进度安排：2012-12-01 内容：通过此界面可以对个人的资料进行修改，点击修改则修改完成。测试 10：名称：注册信息管理测试。 目的：测试注册信息管理界面功能。 进度安排：2012-12-02 内容：每个用户想要加入班级就必须要注册一个账号，这样可以进入班级管理界面。2.3测试1名称：系统身份验证测试目的：测试系统登录界面。进度安排：2012-11-26 内容：用户名、密码、身份输入、合理性检查、合法性检查，系统操作界面显示控制2.3.1进度安排工作内容时间测试人熟悉环境2012-11-26 8:00-9:00工作人员、学生或教师培训2012-11-28 9:00-10:00准备输入数据2012-11-29 10:00-11:00测试2012-11-30 11:00-13:00整理测试结果2010-12-01 13:00-15:00测试组2.3.2条件设备：服务器 (1) 处理器（CPU）：Pentium 900M (推荐Pentium 4 1.2G） (2) 内存容量（RAM）：至少256M（推荐 512M）客户端 (1) 处理器（CPU）：Pentium 133M 或更高 (2) 内存容量（RAM）：64M或更高支持软件：数据库服务器端(1) 操作系统：Microsoft Windows 2003(2) 数据库管理系统：SQL Server 2005，配置TCP/IP协议Web服务器端(1) 操作系统：Microsoft Windows 2003(2) Internet 信息服务（IIS）6.0管理器(3) Visual Studio.NET 2005，配置TCP/IP协议 客户端(1) 操作系统：Windows 98/2000/2003/XP(2) Web浏览器：Internet Explorer 6.0以上或Netscape 4.0以上，配置TCP/IP协议人员：用户：工作人员3名，系统管理员1名，技术方面要求懂得计算机的基本操作。开发任务组：4人，对系统功能有具体的了解，对软件、硬件环境熟悉。2.3.3测试资料需求说明书、概要设计说明书、详细设计说明书、用户手册、操作手册2.3.4测试培训培训内容受训人员从事培训的工作人员学习系统操作测试人员、用户系统开发组学习系统管理测试人员、用户系统开发组3测试设计说明3.1测试1考虑对班级管理系统登录界面是否为空，是否输入错误。3.1.1控制1. 输入：手动2. 操作顺序：各项点击3. 结果记录方法：记录输入信息、提示信息、进入界面3.1.2输入、输出、过程输入数据选择策略命令输出数据用户名a密码a测试当用户名为空时的情况登录按钮“用户名或密码不能为空”的提示框用户名b密码b测试当密码为空时的情况登录按钮“用户名或密码不能为空”的提示框用户名aa密码bb测试当密码错误时的情况登录按钮“用户名或密码”的提示框用户名suanjun密码111测试当用户名错误或不存在时的情况登录按钮“用户名或密码”的提示框用户名111密码111测试用户名和密码都正确的情况登录按钮进入用户或管理界面4评价准则4.1范围此测试计划说明书中的测试用例能基本上包括所有的情况，基本上能反映此软件是否存在错误。其局限性是用例比较多，比较花时间。4.2数据整理由于系统规模不大，输入输出的数据类型简单，所以，我们采用手工方式将测试数据加工成便于评价的适当的形式。4.3尺度1. 以能发现错误为准则2. 能正确完成功能要求。3. 测试用例正确执行，要求输出与预期的输出结果完全一致。3.2班级管理系统用户手册实例用户手册（GB856788）1引言一、概述1编写目的：阐明编写本文档的目的，指出读者对象。编写本用户手册目的是为了什么。文档阅读对象：班级管理系统的用户、测试人员。2项目背景：包括本软件项目的委托单位、开发单位和主管部门；本软件系统与其它系统的关系。3.定义：CMS：班级管理系统简称；SQA：Software Quality Assurance；SCM：Software Configuration Management；SPP：Software Process Plan；CMM：Capability Maturity Model；PM：Project Manager；UCP：Use Case Point4.参考资料:列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括a.本项目经核准的工作任务陈述、合同或上级机关的批文；b.项目开发计划；c.软件需求规格说明书；d.概要设计说明书；e.详细设计说明书；f.本文档中所引用的资料、采用的标准和规范。二、软件概述班级管理系统分为以下五大模块：登录界面、用户管理、班级信息管理、个人资料管理、注册信息管理，各模块的基本功能如下：登录界面模块：用户输入登录名称、登录密码即可进入，当然没有用户名的也可以重新注册，进入班级管理系统。用户管理模块：可以添加、删除用户，此界面普通用户没有提升、撤销、删除、锁定、解锁功能。班级信息管理模块：通过此界面可以对班级信息进行修改，可以对班级实时信息进行调整。注册信息模块：每个用户想要加入班级就必须要注册一个账号，这样可以进入班级管理界面。个人资料模块：通过此界面可以对个人的资料进行修改，点击修改则修改完成。三、运行环境1、硬件环境设备： 服务器 (1) 处理器（CPU）：Pentium 900M (推荐Pentium 4 1.2G） (2) 内存容量（RAM）：至少256M（推荐 512M）客户端 (1) 处理器（CPU）：Pentium 133M 或更高 (2) 内存容量（RAM）：64M或更高2、软件环境数据库服务器端(1) 操作系统：Microsoft Windows 2003(2) 数据库管理系统：SQL Server 2005，配置TCP/IP协议Web服务器端(1) 操作系统：Microsoft Windows 2003(2) Internet 信息服务（IIS）6.0管理器(3) Visual Studio.NET 2005，配置TCP/IP协议 客户端(1) 操作系统：Windows 98/2000/2003/XP(2) Web浏览器：Internet Explorer 6.0以上或Netscape 4.0以上，配置TCP/IP协议四、安装及初始化1、安装准备说明本软件系统的存储形式及数量、需要的环境变量设置、初始化数据等。HRM系统为B/S模式，将安装在应用程序服务器上，以.apsx等文件类型的形式存储，无须设置环境变量和初始化数据。2、安装步骤一步步列出本软件系统的详细安装步骤，包括数据库系统的安装,应用服务器的安装,应用系统的安装等。由于本系统的安装过程简单易懂，只须按照安装提示安装。3、初始化设置说明本软件系统安装后为保证正常运行而需要进行的相关系统设置、数据初始化等。在系统安装过程中已经对系统进行了相关设置和数据初始化，因此无须另外设置和初始化。第4章 实训日记 经过两周的班级管理软件文档实训，使我受益匪浅，学习到了很多平时没有耳闻的知识。我组共5人，我分到的是概要设计和用户手册。第1天：通过我们小组充分的研究跟商量最后确定题目为班级管理软件文档，由组长分配下每个人的具体任务与各自课设的描述方面。第2-5天：在寝室上网搜索一些关于班级管理系统软件文档的一些相关资料再加上去图书馆的书籍大致勾画出课设的大体模块。第6-10天：把收集到的资料进行详细的规划分类整理，一个半成品的实训论文初入端倪。第11天： 搜集了参考文献，并把两周来的实训做了总结。 最后又再一次的对课设进行整体的检查。第5章 实训总结此次设计将要模拟完成建立一个班级管理系统系统，实现信息化。本系统有些类似校友录， 功能齐全，具有很好的人员管理制度。通过这次班级管理系统的设计，让我知道网站的创意、风格、整体框架布局、文字编排、图片的合理利用，空间的合理安排上面等有着许多诸多的要求，需要考虑的面更广，面对的问题也会更多，为我以后工作提供了一个良好的前提。全面系统的理解了编译原理程序构造的一般原理和基本实现方法。把死板的课本知识变得生动有趣，激发了学习的积极性。把学过的计算机编译原理的知识强化，能够把课堂上学的知识通过自己设计的程序表示出来，加深了对理论知识的理解。以前对与计算机操 作系统的认识是模糊的，概念上的，现在通过自己动手做实验，从实践上认识了操作系统是如何处理命令的，如何协调计算机内部各个部件运行，对计算机编译原理的认识更加深刻。课程设计中程序比较复杂，在调试时应该仔细，在程序调试时，注意指针，将不必要的命令去除。我们的这次课程设计是分组进行的，我们组共有4个成员，做的题目是班级管理系统软件文档，我们分别做系统中的不同项目，我被分配做的是“测试设计”和“用户手册”这一项目。班级管理系统能够使得班级管理者快速高效地完成对班级的管理，降低了人力资源管理成本。班级管理系统的总目标是：在计算机网络，数据库和先进的开发平台上，利用现有的软件，配置一定的硬件，开发一个具有开放体系结构的、易扩充的、易维护的、具有良好人机交互界面的班级管理系统。这次课程设计使我得到了充分的锻炼，真是受益匪浅。从中也认识到了团队的重要性。虽然也遇到过很多困难，但通过我们这个小团队的努力以及老师的帮助，都把困难一一克服了。通过这学期的学习，使我又掌握了不少的新知识，使我对软件工程这门课更加感兴趣。参考文献1 刘长青软件工程与软件文档写作 清华大学出版社 2005.82 江开耀软件工程与开发技术 西安电子科技大学出版 2009.23 王素芬软件工程与项目管理 西安电子科技大学出版 2010.34 何晓蓉软件工程与UML案例解析 中国铁道出版社 2010.45 刘竹林软件工程与实践 中国水利水电 2000.46 辛明海 潘孝铭软件文档写作 高等教育出版社 2009.67 肖 刚实用软件文档写作 清华大学出版社 2005.28 顾小航 软件工程技术原理 中国青年出版社 2005.59 赵池龙 实用软件工程 电子工业出版社 2003.310 吴东强 实用软件工程技术 电子工业出版社 2006.611 宋劲松软件文档实例与研究 国防工业出版社 2007.612 胡建伟知识解答与软件文档 西安电子科技大学出版社 2009.413 徐世河 管理信息系统设计教程 电子工业出版社 2003.814 唐任仲 工程应用软件开发技术 化学工业出版社 1999.515