软件文档写作要求

需求分析 差会付出高额代价。
设计
优点：支持结构化软件开 编 码 发、控制软件开发复杂性 、促进软件开发工程化。
缺点：阶段间具有顺序性，各阶 段依赖性强，缺乏灵活性。
测试 运行、维护
软件生存周期模型
2。演化模型—快速原型化方法
需求
需求
设计
开
设计
开
编码 测试
编码 反馈
发
测试
反馈 发
集成
集成
核心系统开发
3. 项目质量保证
文档是进行项目质量审查和评价的重要依据，有效文档的提 供，可以满足项目质量保证人员和审查人员的工作需要。
4. 支持培训与维护 合格的软件文档通常都提供有关软件运行、维护和培训的必
要信息，支持软件产品的应用和维护。 5. 支持软件维护
软件文档提供系统开发的全部必要技术资料，有利于维护人 员熟悉系统，开展维护工作；软件维护文档记载了软件维护过 程中软件及其环境变化的全部信息。 6. 记载软件历史
可行性研究与计划 √ √
需求分析
√ √ √ √
√
√
√
软件设计 编码与单元测试 集成与测试 运行与维护
√
√
√
√
√
√
√
√
√
√
√
√
√ √ √
√
软件文档最终需要回答读者关心的下列问题： 1. 为什么要开发、维护或修改这个软件？(Why) 2. 工作目标要满足哪些需求？(What) 3. 需求应如何实现？(How) 4. 开发、维护或修改的工作应由谁来完成？(Who) 5. 开发工作的时间如何安排？(When) 6. 开发工作在什么环境中实现，所需信息从何而来？(Where)
计语言(必要时用汇编语言)，把详细设计的结果翻译 成用选定的语言书写的程序，并且仔细测试编写出的 每一个模块。
七、综合测试
这个阶段的任务是通过各种类型的测试，使软件 达到预定的要求。
八、软件维护
维护阶段的任务，是通过各种必要的维护活动使 系统持久地满足用户的需要。
第一章 软件文档概念
1.1 为什么需要软件文档？
第二次迭代
优点：与用户见面快、 开发成功率高。
缺点：开发周期长，开发成本 较高。
适用于需求不太明确的大系统
软件生存周期模型
3。螺旋模型
结合了瀑布模型 和演化模型的优 点，加入了风险 分析的因素。
适用于大型软 件开发。
沿着螺旋线在坐标系的四个象限分别表达四个方面的活动：制 定计划、风险分析、实施工程、客户评估。 每转一圈表示一个新的版本的开发。
计算机软件
用户
维护人员
开发人员
管理人员 桥梁作用
1.3 文档的作用
软件文档在产品开发过程中具有十分重要的桥梁作用，主要 反映在以下几个方面：
1. 项目管理的依据
文档将通常“不可见的”软件开发进程转换成“可见的”文 字资料，有利于项目的管理。
2. 技术交流的语言
项目小组内部、项目平行开发的各小组之间进行的交流和联 系，通常都是通过文档来实现的。
软件文档的编制是随着软件生存期各个阶段工作的开展而适时进行的。 其中，有的仅反映某一阶段的工作，有的则需要跨越多个阶段的工作。
可行性研究报告 项目开发计划 软件需求说明书 数据要求说明书 测试计划 概要设计说明书 详细设计说明书 数据库设计说明书 模块开发卷宗 用户手册 操作手册 测试分析报告 开发进度月报 项目总结报告 维护和修改建议
在软件开发过程中遇到的问题找不到解决的办法，致使问题积累起 来形成了日益尖锐的矛盾。
危机实例：IBM公司1963-1966年开发IBM360操作系统，项目花了 5000人-年的工作量，最多时有1000人投入开发工作，写出100万行源程 序，但发行的每一新版本都是上一版1000个错误的修正。
事后负责人F.D.Brooks总结教训时说：“……正象一只逃亡的野兽 落到泥潭中做垂死的挣扎，越是挣扎，陷的越深。最后无法逃脱灭顶的 灾难。程序设计工作正像这样一个泥潭，一批批程序员被迫在泥潭中拼 命挣扎，……谁也没料到问题竟会陷入这样的困境……”
√ √ √ √ √ √ √
谁来做 (Who)
√ √
√
何时做 (When)
何处做 (Where)
√ √ √
√
√
√
√
软件生存周期
软件生存周期模型 描述软件开发过程中各种活动如何执行的模 型。是软件工程过程的简化的抽象描述。
瀑布模型 演化模型 螺旋模型 喷泉模型 增量模型
软件生存周期模型
１. 瀑布模型
适用于系统需求明确、技术成熟工程管理
计划
较严格的场合。对需求不明确的问题，开
发完成后才发现不是用户所需，要纠正偏
软件生存周期
生存周期概念 生存周期模型 生存周期各阶段
软件生存周期
软件生存周期概念
软件生存周期（software life cycle）又称为软件生命期， 生存期。是指从形成开发软件概念起，所开发的软件使用以 后，直到失去使用价值消亡为止的整个过程。
一般来说，整个生存周期包括计划、开发、运行三个时 期，每一个时期又划分为若干阶段。每个阶段有明确的任务 ，这样使规模大、结构复杂和管理复杂的软件开发变得容易 控制和管理。
这个阶段的任务，主要是确定目标系统必须具备哪 些功能。
四、总体设计
这个阶段必须回答的关键问题是：“应该如何解决这 个问题?”
五、详细设计
详细设计阶段的任务就是把解法具体化，设计出 程序的详细规格说明，包括必要的细节，程序员可以 根据它们写出实际的程序代码。
六、编码和单元测试
这个阶段的任务是程序员根据目标系统的性质和 实际环境，选取一种适当的高级程序设
补充：软件工程
• 软件工程:
软件工程是用科学知识和技术原理来定义、开发、维护 软件的一门综合性的交叉学科，软件工程是开发与维护软件 的规范化系统方法。
它综合应用计算机科学、数学及管理科学等原理开发软 件的工程。其中计算机科学、数学用于构造模型与算法，工 程科学用于制定规范、设计范型、评估成本及确定权衡，管 理科学用于用于计划、资源、质量、成本等管理。
工作内容
（1）可行性分析报告 （书面） （2）需求规格说明书 （书面） （3）概要设计说明书 （书面） （4）详细设计说明书 （书面）
要求：根据软件工程技术和项目管理理念，在 组内合理分工，协同工作。
补充：软件工程
软件发展的三个阶段
• 程序设计时代（50-60年代）
–软件指程序，软件开发关注程序编写，用汇编及机器语言
观点：“如果不记下来，它就并不存在”。 正如老子在《道德经》中所述：鱼不可脱于渊，国之利器不可 以示人。
1.2 软件文档的定义
软件文档写作是为了记录目标系统的定义、规划、分析、研究、设计、开 发、应用等各个阶段的设计思想和研究成果。
文档——某种数据媒体和其中所记录的数据。 文档具有永久性，并可供人或机器阅读，通常指专供人阅读的东西。 文档作为计算机软件的重要组成部分，告诉用户如何操作和维护系统，提 供关于未来改进和重新实施所需的信息，在开发人员、维护人员、管理人员、 用户与计算机之间起着重要的桥梁作用。
可行性研究报告 项目开发计划 软件需求说明书 数据要求说明书 概要设计说明书 详细设计说明书 数据库设计说明书 测试计划 测试分析报告
设计说明书 测试分析报告 模块开发卷宗
可行性研究报告 项目开发计划 模块开发卷宗 开发进度月报 项目开发总结报告
用户手册 操作手册
1.6 软件文档编制与软件生存期的关系
软件文档作为“记载软件历史的语言”，可用作未来项目的 一种资源，向潜在用户报道软件的各种有利信息，便于他们判 断自己是否需要该软件提供的服务。
良好的系统文档，显然有助于完成软件的移植，或将软件转 移到各种新的系统环境中去。
ቤተ መጻሕፍቲ ባይዱ
1.4 软件文档的分类
国家标准局在1988年1 月颁布了《计算机软件开 发规范》和《计算机软件 产品开发文件编制指南》， 作为软件开发和文档编制 工作的准则和规程。
毕业设计
论文
教材
教材：软件文档编写 高等教育出版社 辛明海等编
参考资料： 计算机软件工程标准(文档部分GB/T8567-1988、GB/T9385-1988) 国家标准汇编 中国标准出版社
课程学时分配和评分标准
课时分配：每周2课时，共16周 课后作业4次 考试方法：过程化考核，4份报告（小组） 评分标准：
软件文档写作
Software Document Composition
E-mail: cathy1217@
课程重要性
规范软件开发过程
从哪里开 始呢？
设计一个 图书馆管
理系统
课程重要性
软件水平考试
课程重要性
使用说明中的词语，给出图1-2中的数据存储D1~D5的名称。
课程重要性
• 程序系统时代（60-70年代）
–软件指程序及说明书，软件开发包括程序设计和测试，用 高级语言
软件工程时代（70年代以后）
软件指程序、文档、数据，软件开发包括软件生命期，用 软件语言（包括需求定义语言、软件功能语言、软件设计语 言、程序设计语言等）
补充：软件工程
• 软件危机:
摆脱软件危机的出路
：软件开发的工 程化和标准化
可行性研究报告 项目开发计划 软件需求说明书 数据要求说明书 测试计划 概要设计说明书 详细设计说明书 数据库设计说明书 模块开发卷宗 用户手册 操作手册 测试分析报告 开发进度月报 项目总结报告 维护和修改建议
为什么 (Why)
√
√
做什么 (What)
√ √ √ √
√ √ √ √
怎么做 (How)
文档是计算机软件产品的重要组成部分，没有文档就不成其 为软件，也更不能成为软件产品。
软件文档是一种重要的软件工程技术资料。如系统分析文档、 设计文档、版本说明文档……
软件文档的规范编制，在软件开发工作中占有突出的地位和 相当大的工作量。高质量、高效率的编制、分发、管理、维护 文档，及时的变更、修正、扩充和使用文档，对于软件产品的 设计开发、发行使用、变更维护、转让移植、二次开发等，对 于充分发挥软件产品的效益，都有着重要的意义。
用户手册 操作手册 软件需求说明书 数据要求说明书
项目开发计划 模块开发卷宗 开发进度月报 测试计划 测试分析报告 项目开发总结报告
1.5 软件文档与使用者的关系 软件开发中产生的各类文档
面向不同的用户，而软件用户 应该得到的文档也在商业合同 中有明确规定。
软件文档的使用对象
开发人员
维护人员 管理人员 用户
软件生命周期
软件生命期各阶段
软件生命期一般包括以下各阶段：
1. 软件计划与可行性研究 2. 软件系统需求分析 3. 软件设计 4. 软件编码 5. 软件测试与调试 6. 软件运行与维护
软件生命周期
一、问题定义 问题定义阶段必须回答的关键问题是：“要解决的问 题是什么?” 二、可行性研究 此阶段的任务不是具体解决问题，而是研究问题的范 围，探索这个问题是否值得去解决， 是否有可行的解决办法。 三、需求分析
基于软件生存期方法， 可以从形式上将软件文档 大致分成两类：软件开发 过程中需要填写的各种图 表，及应编制的各种技术 文件或管理资料。
软件文档
软件文档根据其产生和 使用的范围，主要划分为 3大类：开发文档、用户 文档和管理文档。
开发文档 用户文档 管理文档
可行性研究报告 项目开发计划 软件需求说明书 数据库设计说明书 概要设计说明书 详细设计说明书
期末考试(60%)＋考勤(20%)＋作业(20%)
软件文档写作过程化考核项目
要求：每组不超过4人，设组长一名； 组长负责：组织、分工、安排进度等； 组长职权：最后根据小组总分分配成员得分； 目的：通过项目，实际体验软件工程各阶段的 主要工作以及相关文档写作，特别注意吸取教 训；学会与他人合作，培养团队精神。因此， 单干户将得不到成绩。