软件文档写作教程

出版时间：2010-5  出版社：电子工业出版社  作者：马平，黄冬梅 著  页数：219  
Tag标签：无  

前言

　　众所周知，软件文档是整个软件开发工作的基础，现代工程化的软件开发离不开软件文档。软件文档体系的建立与软件开发阶段密切相关，是软件开发整个生命周期中必不可少的一部分，软件生命周期始于软件文档，软件文档贯穿着整个软件生命周期。　　作者从事软件工程的教学和研究已有数年的历史，从长期的工作经验中发现，无论是相关专业的学生还是研究开发人员，对软件文档的写作都越来越重视，同时对软件文档写作的写作规范缺乏相应的基础，国内有关软件文档写作的教材也比较少，而且缺乏实际案例的分析。软件文档写作是一门实践性比较强的课程，必须结合实际的软件开发案例进行教学。我们在总结多年的教学和研究经验的基础上，参考国内外最新版本的教材和论文，结合作者多年来跟踪国际上相关领域的最新研发方向的成果编写了这本书。　　本书不同于一般的软件文档写作教材，不仅讲述软件文档写作的基本内容和方法，而且根据软件工程领域的最新发展，结合典型开发案例，力求系统地描述可行性研究报告、项目建议书、招投标文件、需求分析书、概要设计书、详细设计书、项目验收报告和项目总结报告等文档的写作规范和技巧。以数个典型的软件系统开发项目为案例，重点讲述项目建议书，需求分析书、概要设计书、详细设计书和项目验收总结报告的内容、要求、写作技巧和注意事项，指导学生如何书写软件开发过程中的相关文档。　　本书包括以下13章。　　第1章是绪论。主要介绍软件文档的意义、作用和分类等相关知识。　　第2章介绍软件文档的写作规范。其主要内容包括可行性研究报告、项目建议书、招投标文件的写作规范，需求分析书写作规范，概要设计书写作规范，详细设计书写作规范，项目验收总结报告写作规范。　　第3章通过典型案例——某市轨道交通突发事件实时应急集成指挥系统开发过程中的软件文档，讲述软件项目立项阶段项目建议书的内容、要求、写作技巧和注意事项。　　第4章通过典型案例——研究生教务管理系统开发过程中的软件文档，讲述需求分析书的内容、要求、写作技巧和注意事项。　　第5章通过典型案例——奥运综合服务系统开发过程中的软件文档，进一步讲述需求分析书的内容、要求、写作技巧和注意事项。　　第6章通过典型案例——地铁综合信息查询系统开发过程中的软件文档，讲述企业实际项目的需求设计书的内容、要求、写作技巧和注意事项。

内容概要

　　不同于一般的软件文档写作教材，不仅讲述软件文档写作的基本内容和方法，而且根据软件工程领域的最新发展，结合典型开发案例，力求系统地描述可行性研究报告、项目建议书、招投标文件、需求分析书、概要设计书、详细设计书、项目验收报告和项目总结报告等文档的写作规范和技巧。以数个典型的软件系统开发项目为案例，重点讲述项目建议书，需求分析书、概要设计书、详细设计书和项目验收总结报告的内容、要求、写作技巧和注意事项，指导学生如何书写软件开发过程中的相关文档。《软件文档写作教程》可作为软件工程，计算机科学与技术等专业本科生及研究生的参考书，也可作为相关研究开发人员的参考书和工具书。

书籍目录

第1章　绪论	1.1　软件文档的意义	1.2　软件文档的作用	1.3　软件文档的分类	1.4　软件文档必备的条件	1.5　软件文档的管理	本章小结	参考文献	第2章　软件文档的写作规范	2.1　项目立项阶段文档的写作规范	2.2　需求分析书的写作规范	2.3　概要设计书的写作规范	2.4　详细设计书的写作规范	2.5　项目结束阶段文档的写作规范	本章小结	参考文献	习题	第3章　软件项目立项阶段文档写作案例分析——某市轨道交通突发事件实时应急集成指挥系统案例分析	3.1　项目的目的和意义	3.2　国内外研究开发现状和发展趋势	3.3　项目现有工作基础	3.4　项目实施目标	3.5　主要研究开发内容	3.6　社会经济效益分析和风险分析	3.7　年度目标和年度实施计划	3.8　预期主要成果	本章小结	参考文献	习题	第4章　需求分析书案例分析一——研究生教务管理系统案例分析	4.1　引言	4.2　任务概述	4.3　需求规定	4.4　运行环境规定	本章小结	参考文献	习题	第5章　需求分析书案例分析二——奥运综合服务系统案例分析	5.1　系统概述	5.2　功能和非功能需求	5.3　数据需求	5.4　接口需求	5.5　环境需求	本章小结	参考文献	习题	第6章　需求分析书案例分析三——地铁综合信息查询系统案例分析	6.1　概述	6.2　系统需求	6.3　总体结构	6.4　用户培训	本章小结	参考文献	习题	第7章　概要设计书案例分析一——研究生教务管理系统案例分析	7.1　引言	7.2　总体设计	7.3　接口设计	7.4　运行设计	7.5　系统数据结构设计	7.6　系统出错处理设计	本章小结	参考文献	习题	第8章　概要设计书案例分析二——办公自动化系统案例分析	8.1　引言	8.2　概要设计	8.3　各子系统概要设计	8.4　接口设计	8.5　系统出错处理设计	本章小结	参考文献	习题	第9章　概要设计书案例分析三——某企业建筑业信息化系统案例分析	9.1　软件体系结构的确立	9.2　框架选型	9.3　软件开发模型选择	9.4　总体设计	9.5　数据库设计	本章小结	参考文献	习题	第10章　详细设计书案例分析一——研究生教务管理系统案例分析	10.1　引言	10.2　程序系统的结构	10.3　程序设计说明	10.4　算法	10.5　接口	10.6　存储分配	10.7　注释设计	10.8　限制条件	10.9　测试计划	本章小结	参考文献	习题	第11章　详细设计书案例分析二——中国教育信息化系统案例分析	11.1　案例分析	11.2　详细设计的工具	11.3　详细设计书的注意事项	11.4　详细设计的评审	本章小结	参考文献	习题	第12章　软件项目结束阶段文档写作案例分析——校园博客系统案例分析	12.1　测试概述	12.2　测试计划执行情况	12.3　测试总结	12.4　综合评价	本章小结	参考文献	习题	第13章　总结

章节摘录

　　1.设计各模块的实现方法　　如果十个人看着概要设计书进行编码，对于同一个功能模块，也很可能会产生十个不同的实现方法，其中有效率高的最优算法，也有基本实现功能的可行算法。为了使我们的系统具有效率高、性能稳定、容错性强等优点，也必须在编码之前确定最优的算法，避免日后因为达不到前期确定的性能要求而返工。于是我们必须在详细设计阶段确定模块功能实现中的最优算法，预见技术难点，分析数据流等，这些问题不应该留待编码遇到的时候才考虑。　　2.成为编码人员的指挥棒　　我们心目中最理想的详细设计书是这样的，即使是一个对本系统一无所知的编程人员，按照详细设计书中包含的内容，也能很好的完成这部分的编码任务。换句话说，从详细设计书到编码的工作应仅仅是一个翻译工作，而不应存在任何的设计工作，所有设计工作应在编码之前完成。　　3.成为单元测试的依据　　方法是系统中最小的功能单位，单元测试的着眼点就是这些方法。在详细设计书中写着这些方法的输人参数，输出结果，测试用例就可以根据这些输入参数进行组合，考虑正常值、临界值、无效值，从而形成单元测试的测试用例。　　2.4.2 详细设计书的基本要求　　1.全面　　如果说概要设计书的全面是针对整个软件系统的全面，那么详细设计书的全面就是针对整个模块的全面。整个系统只需要撰写一份概要设计书，但是详细设计书却必须有多份，因为我们需要为每个模块单独撰写详细设计书，即使是简单的功能模块也必须写详细设计书，哪怕是简单地描述该模块的实现，一方面是为了对付人类遗忘的天性，另一方面是为了与下一个接手这个软件系统的人进行平滑的交接。不将所有模块的详细设计都写在一个文档中，这样做避免了文档过大，而且易于查找。详细设计书中应该详尽地写下本模块的处理流程，至于模块的输入、输出、异常处理、响应速度等方方面面也要考虑周全。　　所以说，全面，既是指对于该软件系统所有功能模块都要进行详细设计，又是指对于某个模块的设计要全面。