第一章--软件文档写作-基本介绍

7. 《安装手册》--包括系统环境、运行平台、产品安装过程、 初始环境设置、安装记录等。 8. 《使用手册》--包括产品简介、功能列表、功能描述和解 释、功能操作、客户服务和联系方式等。 9. 《维护手册》--包括产品简介、系统须知、初始环境设置、 系统配置、数据管理和备份、技术问题解答和联系方式等。 10. 《用户报告》--包括产品简介、购买时间、使用目的、 使用时间、使用地点、实施过程、出现问题和解决、产品总结 和建议等。 11.《销售培训》--包括项目简介、产品功能、产品特点、商 业优势、系统运行环境、适用范围、目标客户等。
可行性研究报告； 项目开发计划； 软件需求说明书； 数据要求说明书； 概要设计说明书； 详细设计说明书； 数据库设计说明书； 用户手册； 操作手册； 模块开发卷宗； 测试计划； 测试分析报告； 开发进度月报； 项目开发总结报告。 本指南将给出开发过程中建议产生的这十四种文件的编制指 导，同时，本指南也是这十四种文件的 编写质量的检验准则。 但是，本指南并未涉及软件开发过程中如何填写工作表格的问题。
c．记录开发过程中的技术信息，便于协调以后的软件开发、 使用和修改； d．提供对软件的有关运行、维护和培训的信息，便于管理 人员、开发人员、操作人员和用户之间相 互了解彼此的工作； e．向潜在用户报导软件的功能和性能，使他们能判定该软 件能否服务于自己的需要。 换言之，本指南认为：文件的编制必须适应计算机软件整个 生存周期的需要。 计算机软件所包含的文件有两类：一类是开发过程中填写的 各种图表，可称之为工作表格；另一类 则是应编制的技术资料 或技术管理资料，可称之为文件。本指南规定软件文件的编制形 式，并提供对这 些规定的解释。本指南的目的是使得所编制的 软件文件确实能够起到软件文件应该发挥的作用。 2 范围 本指南是一份指导性文件。本指南建议，在一项计算机软件 的开发过程中，一般地说，应该产生十四种文件。这十四种文件 是：
4 软件生存周期与各种文件的编制 一项计算机软件，从出现一个构思之日起，经过这项软件开 发成功投入使用，直到最后决定停止使 用，并被另一一项软件 代替之时止，被认为是该软件的一个生存周期。一般地说这个软 件生存周期可以分成以下六个阶段： 可行性与计划研究阶段 需求分析阶段 设计阶段 实现阶段 测试阶段 运行与维护阶段 在可行性研究与计划阶段内，要确定该软件的开发目标和总 的要求，要进行可行性分析、投资--收益分析、制订开发计划， 并完成应编制的文件。 在需求分析阶段内，由系统分析人员对被设计的系统进行系 统分析，确定对该软件的各项功能、性能需求和设计约束，确定 对文件编制的要求，作为本阶段工作的结果，一般地说，软件需 求说明书、数据要求说明书和初步的用户手册应该编写出来。
授课内容： 采取讲座方式，用案例介绍各类软件文档的写作。 写作工具： Win Word Docbook
作业及考试要求： 平时占50% 考查占50%
ቤተ መጻሕፍቲ ባይዱ
软件文档知多少？ 软件文档知多少？ 如今，软件开发越来越复杂，软件功能也越来越丰富。而 几乎所有成熟的商业软件，都是靠一个开发团队齐心协力的血 汗结晶。“罗马不是一天建成的！”，当我们震撼于Microsoft Windows的惊世巨著的同时，也道听途说了微软公司软件工程是 如何的完善规范。的确，集数百名员工几年的共同努力之大成， 软件项目管理的成败是控制开发成本的关键环节。这里面，少 不了贯穿其中的重要步骤----软件文档。 软件文档可以分为开发文档和产品文档两大类。 开发文档包括：《功能要求》、《投标方案》、《需求分 析》、《技术分析》、《系统分析》、《数据库文档》、《功 能函数文档》、《界面文档》、《编译手册》、《QA文档》、 《项目总结》等。 产品文档包括：《产品简介》、《产品演示》、《疑问解 答》、《功能介绍》、 《技术白皮书》、《评测报告》、《安 装手册》、《使用手册》、《维护手册》、 《用户报告》、 《销售培训》等。
软件文档写作
Software Document Writing
学习软件文档写作的目的： 1. 要发展我国的软件产业就必须学习国外先进的软件开发 技术和方法，把软件开发工程化、规范化，进行综合性管理， 而软件文档的规范化撰写，是此项工作的第一步。 2. 市场的需求，具有软件文档写作经验已成为许多软件公司 招聘的一项基本要求。 3. 对于工程团队及技术产品的最终用户而言，软件文档的撰 写是必不可缺的一部分。目前的软件文档存在诸多问题，影响 了其有效性。 4. 软件开发流程的要求。美国水平比较高的软件公司软件开 发流程十分规范，技术文档和使用文档非常细致，量非常大。 按照一位经理的说法，是“所有的事情都有文档记录”。不仅 如此，美国更有technical writer(技术写作师)这个职业。国 内这方面的差距较大：软件工程师视文档为负担，项目经理本 身是软件工程师出身，更加没有动力实施这些规范，公司老总 可能又不懂软件开发管理，于是低水平现状是想躲都躲不掉了。
二、产品文档 1. 《产品简介》--包括公司背景、产品概念、适用范围、产 品功能、功能特点、运行要求和公司联系地址。 2. 《产品演示》--包括公司简介、产品背景、产品描述、产 品特点、产品作用、适用范围、使用分析、功能模块、解决问题、 合作伙伴、成功案例等。一般用PowerPoint或者VCD录制软件实 现。 3. 《疑问解答》--列出用户关心的问题和处理方法。用于解 答软件的操作功能和解决用户的疑难问题。 4. 《功能介绍》--以《需求分析》为书写基础，包括软件介 绍、软件结构、功能列表、功能描述和公司联系地址。 5. 《技术白皮书》--以《技术分析》为书写基础，包括功能 实现、技术选型、关键技术问题的解决、技术方案特点、技术升 级方向等。 6. 《评测报告》--第三方权威评测报告。包括评测目的、评 测范围、评测环境、评测内容、实测数据、性能表现、结果分析 和评测总结等。
4. 《技术分析》--包括技术选型、技术比较、开发人员、关 键技术问题的解决、技术风险、技术升级方向、技术方案评价， 竞争对手技术分析等。以《需求分析》为基础，进行详细的技 术分析(产品的性能和实现方法)，列出本项目需要使用什么技术 方案，为什么，有哪些技术问题要解决 ，估计开发期间会碰到 什么困难，技术方案以后如何升级，对本项目的技术有什么评 价等。 5. 《系统分析》--包括功能实现、模块组成、功能流程图、 函数接口、数据字典、软件开发需要考虑的各种问题等。以 《需求分析》为基础，进行详细的系统分析(产品的开发和实现 方法)，估计开发期间需要把什么问题说明白，程序员根据《系 统分析》，开始在项目主管的带领下进行编码。 6. 《数据库文档》--包括数据库名称、表名、字段名、字段 类型、字段说明、备注、字段数值计算公式等。以《系统分析》 为基础，进行详细的数据库设计。必要时可以用图表解说，特 别是关系数据库。
一、开发文档 1. 《功能要求》--来源于客户要求和市场调查，是软件开发 中最早期的一个环节。客户提出一个模糊的功能概念，或者要 求解决一个实际问题，或者参照同类软件的一个功能。有软件 经验的客户还会提供比较详细的技术规范书，把他们的要求全 部列表书写在文档中，必要时加以图表解说。这份文档是需求 分析的基础。 2. 《投标方案》--根据用户的功能要求，经过与招标方沟通 和确认，技术人员开始书写《投标方案》，方案书一般包括以 下几个重要的章节： 前言--项目背景、公司背景和业务、技术人员结构、公司的 成功案例介绍等。 需求分析--项目要求、软件结构、功能列表、功能描述、注 意事项等。 技术方案--总体要求和指导思想、技术解决方案、软件开发 平台、网络结构体系等。
一般地说，一个软件总是一个计算机系统（包括硬件、固 件和软件）的组成部分。鉴于计算机系统的 多样性，本指南一 般不涉及整个系统开发中的文件编制问题，本指南仅仅是软件 开发过程中的文件编制指南。 3 文件的使用者 对于使用文件的人员而言，他们所关心的文件的种类，随 他们所承担的工作而异。 管理人员：可行性研究报告，项目开发计划，模块开发卷 宗，开发进度月报，项目开发总结报告； 开发人员：可行性研究报告，项目开发计划，软件需求说 明书，数据要求说明书， 概要设计说明书，详细设计说明书， 数据库设计说明书，测试计划，测试分析报告； 维护人员：设计说明书，测试分析报告，模块开发卷宗； 用户：用户手册， 操作手册。 尽管本指南提出了在软件开发中文件编制的要求，但并不 意味着这些文件都必须交给用户。一项软件的用户应该得到的 文件的种类由供应者与用户之间签订的合同规定。
项目管理--描述公司的软件开发流程、工程实施服务、组织 和人员分工、开发进度控制、软件质量保证、项目验收和人员 培训、软件资料文档等。 技术支持--公司的技术支持和服务介绍、服务宗旨和目标、 服务级别和响应时间、技术服务区域、技术服务期限、授权用 户联系人等。 系统报价--软、硬件平台报价列表、软件开发费用、系统维 护费用等。 项目进度--整个项目的进度计划，包括签署合同、项目启动、 需求分析、系统分析、程序开发、测试维护、系统集成、用户 验收、用户培训等步骤的时间规划。 3. 《需求分析》--包括产品概述、主要概念、操作流程、功 能列表和解说、注意事项、系统环境等。以《功能要求》为基 础，进行详细的功能分析(包括客户提出的要求和根据开发经验 建议的功能)，列出本产品是什么，有什么特殊的概念，包括那 些功能分类，需要具备什么功能，该功能的操作如何，实现的 时候该注意什么细节，客户有什么要求，系统运行环境的要求 等。这里的功能描述跟以后的使用手册是一致的。
7. 《功能函数文档》--包括变量名、变量初植、功能，函数 名，参数，如何调用、备注、注意事项等。以《系统分析》为基 础，进行详细的说明，列出哪个功能涉及多少个函数，以便以后 程序员修改、接手和扩展。 8. 《界面文档》--包括软件外观、界面素材、编辑工具、文 件名、菜单、按钮和其它界面部件的要求，这里与软件完成后的 运行界面是一致的。 9. 《编译手册》--包括服务器编译环境、操作系统、编译工 具、GNU的C++编译器版本信息、目录说明、程序生成、源程序 文件列表、Makefile配置及其相关程序的对应关系列表。客户端 的编译过程、编译结果、编译示例、编译环境、操作系统、编译 工具、源文件列表和制作安装程序的过程。 10. 《QA文档》--包括产品简介、产品原理、产品功能列表、 功能描述、功能流程、执行结果、数据库结构、测试要求等，提 供给软件测试人员使用。 11. 《项目总结》--包括项目简介、项目参与人员和开发时间、 项目风险管理过程、项目功能列表、项目结构特点、技术特点、 对项目的升级建议、对以后的项目的建议、人员素质情况等。