《软件文档写作要求xcz》由会员分享，可在线阅读，更多相关《软件文档写作要求xcz（70页珍藏版）》请在金锄头文库上搜索。
1、第四章 软件文档写作要求,主要内容,4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 4.4建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类,4.1 软件文档管理指南,软件文档管理指南（GB166801996）制定的目的在于协助管理者在他们的机构中产生有效的文档。其主要内容主要涉及文档编制的策略、标准、规程、资源和计划,本指南规定管理者承担的职责：,（1）要求哪些类型的文档；（2）文档包含的内容；（3）达到何种级别的质量水平；（4）何时产生何种文档；（
2、5）如何保存、维护文档以及如何进行通信。,4.2 软件文档的编写原则,文档编制的原则,文档编写应适应文档的读者,文档编写应有必要的重复性,文档编写应具有一定灵活性,文档种类,文档详细程度,文档的扩展,节的扩张与缩并,程序设计的表现形式,文档的表现形式,文档其他种类,根据一个项目的规模、复杂性和成败风险，决定应编制的文档种类及其详细,4.2 软件文档的编写原则,文档编制的原则,文档编写应适应文档的读者,文档编写应有必要的重复性,文档编写应具有一定灵活性,文档种类,文档详细程度,文档的扩展,节的扩张与缩并,程序设计的表现形式,文档的表现形式,文档其他种类,当被开发的项目规模非常大时，可以将一个文档
3、拆分成多个卷进行编制。,项目开发计划可能包括：l 质量保证计划；l 配置管理计划；l 用户培训计划；l 安装实施计划。系统设计说明书可分写成：l 系统设计说明书；l 子系统设计说明书。程序设计说明书可分写成：l 程序设计说明书；l 接口设计说明书；l版本说明。,操作手册可分成以下内容：操作手册；安装实施过程；测试计划可分成以下内容：测试计划测试设计说明测试规程测试用例测试分析报告可分成以下内容：综合测试报告验收测试报告。项目开发总结报告也可分成项目开发总结报告和资源环境统计。,4.2 软件文档的编写原则,文档编制的原则,文档编写应适应文档的读者,文档编写应有必要的重复性,文档编写应具有一定灵活
4、性,文档种类,文档详细程度,文档的扩展,节的扩张与缩并,程序设计的表现形式,文档的表现形式,文档其他种类,所有的章节都可以进一步细分或缩并，以适应实际需要要。,4.2 软件文档的编写原则,文档编制的原则,文档编写应适应文档的读者,文档编写应有必要的重复性,文档编写应具有一定灵活性,文档种类,文档详细程度,文档的扩展,节的扩张与缩并,程序设计的表现形式,文档的表现形式,文档其他种类,程序的设计表现形式可以使用多种形式，如流程图、判定表、等其他表现形式,例：P.86 航空行李托运费的算法按规定：重量不超过30公斤的行李可免费托运。重量超过30公斤时，对超运部分，头等舱国内乘客收4元/公斤；其它舱位
5、国内乘客收6元/公斤；外国乘客收费为国内乘客的2倍；残疾乘客的收费为正常乘客的1/2。,4.2 软件文档的编写原则,文档编制的原则,文档编写应适应文档的读者,文档编写应有必要的重复性,文档编写应具有一定灵活性,文档种类,文档详细程度,文档的扩展,节的扩张与缩并,程序设计的表现形式,文档的表现形式,文档其他种类,文档的表现形式可以使用自然语言，也可以使用形式化语言,4.2 软件文档的编写原则,文档编制的原则,文档编写应适应文档的读者,文档编写应有必要的重复性,文档编写应具有一定灵活性,文档种类,文档详细程度,文档的扩展,节的扩张与缩并,程序设计的表现形式,文档的表现形式,文档其他种类,主要内容,
6、4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 4.4建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类,4.3 制定文档的编写策略,文档策略是由上级（资深）管理者提出并支持的，对下级开发单位或开发人员提供指导。策略规定主要的方向，而不是规定做什么或如何做。,文档需要覆盖整个软件生存期,文档应是可管理的,文档应适合于它的读者,文档效应应贯穿到软件的整个开发过程中,文档标准应被标识和使用,应规定支持工具,文档策略,评估现有策略条款的有效性和完整性的文档检
7、查表,适当的文档的决策作出了吗？涉及文档的策略声明发布了吗？负责开发文档和产品文档编写工作的人员或部门落实了吗？用于文档编制的资源落实了吗？负责文档质量的人员或部门落实了吗？各管理层次和组织各分支之间的各种关系确定了吗？对于文档的编制、分发和维护等方面是否确定了职责、所需活动和联系途径？所有的文档要求已列入整个项目开发计划表中了吗？适用的文档标准已确定了吗？是否已考虑采用支持工具和自动化的文档编制？,主要内容,4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 4.4建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要
8、求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类,4.4建立文档的企业标准,是不是每个人编写的文档质量都一样？如何确定文档的质量？如何保证？评价文档的质量主要从两个方面：文档的结构：其质量从各个组成部分的顺序和总体安排的简单性来测定。文档的内容：从文档内容的正确性、完整性和明确性来判断。,4.4建立文档的企业标准,在一个机构内部应采用一些标准和指南:软件生存期模型文档类型和相互关系文档质量标准和指南作用：（1）决定如何实现文档任务（2）提供一些准则以评价该机构内所产生的软件文档的完整性、可用性和适合性。尽可能地采用现行的国家和国际标准，若现行的标准不适用，机构应制订自己的标准,4
9、.4建立文档的企业标准,1.选择软件生存期模型2.规定文档类型和内容3.确定文档的质量等级,1.选择软件生存期模型,软件生存周期模型无关紧要, 但阶段和相应的文档必须清晰定义、计划、并且适用具体的软件项目。管理者应选择一个软件生存期模型并保证该模型在他们机构内是适用的生存周期选择对管理者作用：（1）软件周期中相应的阶段划分与各阶段定义将有助于监控软件项目的进展，（2）相应于特定阶段生成的文档可用作该阶段的评审通过和完成的检验点,2规定文档类型和内容,软件文档归入如下三种类别：开发文档描述开发过程本身产品文档描述开发过程的产物管理文档记录项目管理的信息以上内容已在P18软件文档的分类中讲过。,3
10、. 文档的质量等级,文档的质量可以按文档的形式和要求划分为四级：（1）最低限度文档（1级文档）：1级文档适合开发工作量低于一个人月的软件。该文档应包含程序清单、开发记录、测试数据和程序简介。（2）内部文档（2级文档）：2级文档可用于在精心研究后被认为没有与其他用户共享资源的专用程序。除1级文档提供的信息外，2级文档还包括程序清单内足够的注释以帮助用户安装和使用程序。,（3）工作文档（3级文档）：3级文档适合于由同一单位内若干人联合开发的程序，或可被其他单位使用的程序。（4）正式文档（4级文档）：4级文档适合那些要正式发行供普遍使用的软件产品。关键性程序或具有重复管理应用性质（如工资计算）的程序
11、需要4级文档。4级文档遵守GB 8567的有关规定。,质量从第1级到第四级，需要的投入和资源逐级增加，质量保证机构必须处于适当的行政地位以保证达到期望的质量等级。 为了保证文档的质量，主要从一下几个方面：评审鉴定责任到人采用制作工具,主要内容,4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 4.4建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类,4.5制定文档的编制计划 （文档计划）,1制定文档计划的目的2文档计划的特点3文档计划的内容4文档计划制定
12、与评估,1制定文档计划的目的,指出未来的各项活动文档计划是文档重要性的具体依据管理部门文档工作责任的备忘录,2文档计划的特点,文档计划可以是整个项目计划的一部分或是一个独立的文档对于小的非正式的项目文档计划可能只有一页纸对于较大的项目文档计划可能是一个综合性的正式文档，这样的文档计划应遵循各项严格的标准及正规的评审和批准过程。编制计划的工作应及早开始，对计划的评审应贯穿项目的全过程。需要修改时必须加以修改导致对计划作适当修改的常规评审应作为该项目工作的一部分所有与该计划有关的人员都应得到文档计划,3文档计划的内容,此外：（1）文档计划规定每个文档要达到的质量等级，以及为了达到期望的结果必须考虑
13、哪些外部因素。（2）文档计划还确定该计划和文档的分发，并且明确叙述参与文档工作的所有人员的职责。,4文档计划制定与评估,可按照GB16680-1996软件文档管理指南附录B中文档计划检查表来制定一个文档计划或评估现有文档计划的完整性。,主要内容,4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 4.4建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类,4.6 制定文档编制规程（文档规程）,1标准、规范、规程的概念 2文档规程编制特点3文档管理规程检查表4
14、文档编制规程中规定的实施程序与技术要求,1标准、规范、规程的概念,标准：软件工程标准是为在软件工程领域内获得最佳结果规定共同的和重复使用的规则、导则或特性的文件，该文件经协商一致制定并经一个公认机构批准，以科学、技术和实践经验的综合成果为基础，以促进最佳社会效益为目的。规范是在工农业生产和工程建设中，对设计、施工、制造、检验等技术事项所做的一系列规定；规程是对作业、安装、鉴定、安全、管理等技术要求和实施程序所做的统一规定。标准、规范、规程都是标准的一种表现形式，习惯上统称为标准，只有针对具体对象才加以区别。,2文档编制规程特点,文档编制规程提出关于文档的计划、编制、评审、制作和分发的逻辑顺序。
15、这些规程内含审批、质量保证及若干控制点，概述修改步骤、存储和维护要求以及更新方法。,3文档管理规程检查表,附录C中的检查表能帮助设计合适的规程或有助于评定现有规程的有效性 。,4文档编制规程中规定的实施程序与技术要求,文档计划制定文档编写文档编号文档评审文档签署文档归档与保管文档维护,4文档编制规程中规定的实施程序与技术要求,文档计划制定参见前一章节文档编写编写文档应注意以下几点：文档编写时间应与软件开发同步，在软件生存期的每一个阶段应完成相应的文档编写工作。按文档计划规定的文档数量和质量要求编写文档。按GB/T8567-1988或本单位指定的标准内容和格式编写相应文档文档用纸的格式由各单位按有关标准规定执行每个文档必须装订成册并加封面和目次归档用的文档还应有扉页用于各责任者的签署,4文档编制规程中规定的实施程序与技术要求,文档编号为便于管理软件文档应按编号法进行编号，编号方法有十进分类法；隶属法等等。各单位可根据本单位实际情况，确定一种编号方法。不论何种方法编号应具有唯一性。具体的需求分析说明书的编号方法为：文档，软件名称，文档类型，文档建立日期。,4文档编制规程中规定的实施程序与技术要求,文档评审（1）文档评审重要性（2）评审的内容（3）需求评审（4）设计评审（5）评审程序,
