4软件文档写作要求xcz

1、第四章 软件文档写作要求1主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类24.1 软件文档管理指南 软件文档管理指南（GB166801996）制定的目的在于协助管理者在他们的机构中产生有效的文档。其主要内容主要涉及文档编制的策略、标准、规程、资源和计划3本指南规定管理者承担的职责：（1）要求哪些类型的文档；（2）文档包含的内容；（3）达到何种级别的质量水平；（4）何时产生何种文档；（5）如何保

2、存、维护文档以及如何进行通信。 44.2 软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细程度文档的扩展节的扩张与缩并程序设计的表现形式文档的表现形式 文档其他种类 根据一个项目的规模、复杂性和成败风险，决定应编制的文档种类及其详细54.2 软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细程度文档的扩展节的扩张与缩并程序设计的表现形式文档的表现形式 文档其他种类 当被开发的项目规模非常大时，可以将一个文档拆分成多个卷进行编制。6项目开发计划可能包括

3、：l 质量保证计划；l 配置管理计划；l 用户培训计划；l 安装实施计划。系统设计说明书可分写成：l 系统设计说明书；l 子系统设计说明书。程序设计说明书可分写成：l 程序设计说明书；l 接口设计说明书；l版本说明。 7操作手册可分成以下内容：操作手册；安装实施过程；测试计划可分成以下内容：测试计划测试设计说明测试规程测试用例测试分析报告可分成以下内容：综合测试报告验收测试报告。项目开发总结报告也可分成项目开发总结报告和资源环境统计。84.2 软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细程度文档的扩展节的扩张与缩并程

4、序设计的表现形式文档的表现形式 文档其他种类 所有的章节都可以进一步细分或缩并，以适应实际需要要。94.2 软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细程度文档的扩展节的扩张与缩并程序设计的表现形式文档的表现形式 文档其他种类 程序的设计表现形式可以使用多种形式，如流程图、判定表、等其他表现形式10例：P.86 航空行李托运费的算法按规定：重量不超过30公斤的行李可免费托运。重量超过30公斤时，对超运部分，头等舱国内乘客收4元/公斤；其它舱位国内乘客收6元/公斤；外国乘客收费为国内乘客的2倍；残疾乘客的收费为正常乘客

5、的1/2。 1112134.2 软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细程度文档的扩展节的扩张与缩并程序设计的表现形式文档的表现形式 文档其他种类文档的表现形式可以使用自然语言，也可以使用形式化语言144.2 软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细程度文档的扩展节的扩张与缩并程序设计的表现形式文档的表现形式 文档其他种类15主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准

6、4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类164.3 制定文档的编写策略文档策略是由上级（资深）管理者提出并支持的，对下级开发单位或开发人员提供指导。策略规定主要的方向，而不是规定做什么或如何做。 文档需要覆盖整个软件生存期 文档应是可管理的文档应适合于它的读者文档效应应贯穿到软件的整个开发过程中文档标准应被标识和使用 应规定支持工具文档策略17评估现有策略条款的有效性和完整性的文档检查表适当的文档的决策作出了吗？涉及文档的策略声明发布了吗？负责开发文档和产品文档编写工作的人员或部门落实了吗？用

7、于文档编制的资源落实了吗？负责文档质量的人员或部门落实了吗？各管理层次和组织各分支之间的各种关系确定了吗？对于文档的编制、分发和维护等方面是否确定了职责、所需活动和联系途径？所有的文档要求已列入整个项目开发计划表中了吗？适用的文档标准已确定了吗？是否已考虑采用支持工具和自动化的文档编制？ 18主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类19建立文档的企业标准是不是每个人编写的文档质量都一样？

8、如何确定文档的质量？如何保证？评价文档的质量主要从两个方面：文档的结构：其质量从各个组成部分的顺序和总体安排的简单性来测定。文档的内容：从文档内容的正确性、完整性和明确性来判断。20建立文档的企业标准在一个机构内部应采用一些标准和指南:软件生存期模型文档类型和相互关系文档质量标准和指南作用：（1）决定如何实现文档任务（2）提供一些准则以评价该机构内所产生的软件文档的完整性、可用性和适合性。尽可能地采用现行的国家和国际标准，若现行的标准不适用，机构应制订自己的标准21建立文档的企业标准1.选择软件生存期模型2.规定文档类型和内容3.确定文档的质量等级221.选择软件生存期模型软件生存周期模型无关

9、紧要, 但阶段和相应的文档必须清晰定义、计划、并且适用具体的软件项目。管理者应选择一个软件生存期模型并保证该模型在他们机构内是适用的生存周期选择对管理者作用：（1）软件周期中相应的阶段划分与各阶段定义将有助于监控软件项目的进展，（2）相应于特定阶段生成的文档可用作该阶段的评审通过和完成的检验点232规定文档类型和内容软件文档归入如下三种类别：开发文档描述开发过程本身产品文档描述开发过程的产物管理文档记录项目管理的信息以上内容已在P18软件文档的分类中讲过。243. 文档的质量等级 文档的质量可以按文档的形式和要求划分为四级：（1）最低限度文档（1级文档）：1级文档适合开发工作量低于一个人月的软

10、件。该文档应包含程序清单、开发记录、测试数据和程序简介。（2）内部文档（2级文档）：2级文档可用于在精心研究后被认为没有与其他用户共享资源的专用程序。除1级文档提供的信息外，2级文档还包括程序清单内足够的注释以帮助用户安装和使用程序。25（3）工作文档（3级文档）：3级文档适合于由同一单位内若干人联合开发的程序，或可被其他单位使用的程序。（4）正式文档（4级文档）：4级文档适合那些要正式发行供普遍使用的软件产品。关键性程序或具有重复管理应用性质（如工资计算）的程序需要4级文档。4级文档遵守GB 8567的有关规定。26质量从第1级到第四级，需要的投入和资源逐级增加，质量保证机构必须处于适当的行

11、政地位以保证达到期望的质量等级。 为了保证文档的质量，主要从一下几个方面：评审鉴定责任到人采用制作工具27主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类28制定文档的编制计划 （文档计划）1制定文档计划的目的2文档计划的特点3文档计划的内容4文档计划制定与评估291制定文档计划的目的指出未来的各项活动文档计划是文档重要性的具体依据管理部门文档工作责任的备忘录302文档计划的特点文档计划可以是整

12、个项目计划的一部分或是一个独立的文档对于小的非正式的项目文档计划可能只有一页纸对于较大的项目文档计划可能是一个综合性的正式文档，这样的文档计划应遵循各项严格的标准及正规的评审和批准过程。编制计划的工作应及早开始，对计划的评审应贯穿项目的全过程。需要修改时必须加以修改导致对计划作适当修改的常规评审应作为该项目工作的一部分所有与该计划有关的人员都应得到文档计划313文档计划的内容此外：（1）文档计划规定每个文档要达到的质量等级，以及为了达到期望的结果必须考虑哪些外部因素。（2）文档计划还确定该计划和文档的分发，并且明确叙述参与文档工作的所有人员的职责。324文档计划制定与评估可按照GB16680-

13、1996软件文档管理指南附录B中文档计划检查表来制定一个文档计划或评估现有文档计划的完整性。3334主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类354.6 制定文档编制规程（文档规程）1标准、规范、规程的概念 2文档规程编制特点3文档管理规程检查表4文档编制规程中规定的实施程序与技术要求361标准、规范、规程的概念标准：软件工程标准是为在软件工程领域内获得最佳结果规定共同的和重复使用的规则、

14、导则或特性的文件，该文件经协商一致制定并经一个公认机构批准，以科学、技术和实践经验的综合成果为基础，以促进最佳社会效益为目的。规范是在工农业生产和工程建设中，对设计、施工、制造、检验等技术事项所做的一系列规定；规程是对作业、安装、鉴定、安全、管理等技术要求和实施程序所做的统一规定。标准、规范、规程都是标准的一种表现形式，习惯上统称为标准，只有针对具体对象才加以区别。372文档编制规程特点文档编制规程提出关于文档的计划、编制、评审、制作和分发的逻辑顺序。这些规程内含审批、质量保证及若干控制点，概述修改步骤、存储和维护要求以及更新方法。383文档管理规程检查表附录C中的检查表能帮助设计合适的规程或

15、有助于评定现有规程的有效性 。394文档编制规程中规定的实施程序与技术要求文档计划制定文档编写文档编号文档评审文档签署文档归档与保管文档维护404文档编制规程中规定的实施程序与技术要求文档计划制定参见前一章节文档编写编写文档应注意以下几点：文档编写时间应与软件开发同步，在软件生存期的每一个阶段应完成相应的文档编写工作。按文档计划规定的文档数量和质量要求编写文档。按GB/T8567-1988或本单位指定的标准内容和格式编写相应文档文档用纸的格式由各单位按有关标准规定执行每个文档必须装订成册并加封面和目次归档用的文档还应有扉页用于各责任者的签署414文档编制规程中规定的实施程序与技术要求文档编号为

16、便于管理软件文档应按编号法进行编号，编号方法有十进分类法；隶属法等等。各单位可根据本单位实际情况，确定一种编号方法。不论何种方法编号应具有唯一性。具体的需求分析说明书的编号方法为：文档，软件名称，文档类型，文档建立日期。424文档编制规程中规定的实施程序与技术要求文档评审（1）文档评审重要性（2）评审的内容（3）需求评审（4）设计评审（5）评审程序43文档评审（1）文档评审重要性a.文档评审十分重要。文档评审必须与技术评审结合起来b.为了提高软件产品的质量,一个有效的方法就是在软件开发的每个阶段对该阶段所形成的文档进行严格的评审.这样可尽早发现问题并及时采取措施予以解决,从而确保文档内容的正确

17、性,避免或减少大的返工,同时为进入下一阶段的工作做好组织上和技术上的准备c.文档评审作为正规评审的一部分，可以保证文档不但正确，而且内容最新。 444文档编制规程中规定的实施程序与技术要求文档评审（2）评审的内容a.需求评审和设计评审对所有描述开发工作和产品的文档进行评审是正规评审过程的组成部分，一开始特别重要的是需求规格说明和设计规格说明的评审。无论项目大小或项目管理的正规化程度,需求评审和设计评审是必不可少的.需求必须说明清楚,用户和开发者双方都必须理解需求,为了能把需求转换成程序及程序成分,设计的细节须经同意并写成文档.b.其它评审 45464文档编制规程中规定的实施程序与技术要求文档评

18、审（3）需求评审案例：需求评审之道474文档编制规程中规定的实施程序与技术要求文档评审(4)设计评审 48文档评审(5)评审程序494文档编制规程中规定的实施程序与技术要求文档签署文档签署程序软件文档签署者（P64）注意：签署不允许代签修改单的签署与被修改的文档签署相同编写审核会签标准化批准504文档编制规程中规定的实施程序与技术要求文档归档与保管软件产品的文档是软件开发过程的真实记录,是重要的信息资源, 因此必须实行集中统一管理,使之完善安全并能有效地利用.文档归档文档保管文档维护软件产品在投入运行后往往还会有程序错误、文档错误以及适应新的环境和需求而要求增加或修改软件及其相关文档等情况。因

19、此必须对软件产品及其文档进行维护。51主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类524.7 软件文档的质量要求高质量软件文档特征 创建高质量的软件文档体系 软件文档的质量评价53高质量软件文档特征（1）针对性：分清读者、适应需要。（2）精确性：行文确切，避免多义。（3）清晰性：力求简明，运用图表。（4）完整性：自称体系，避免引用。（5）灵活性：大的扩展，小的合并。（6）可追溯性：逐步扩展，

20、前后照应。54创建高质量的软件文档体系 （1）制定文档策略制定文档策略的过程为:首先是选择软件生命周期模型，然后规定文档的类型和内容，最后是确定文档的质量等级。 （2）编写具体的文档 （3）文档的评审 55软件文档的质量评价软件文档的质量取决于其可用性，可从以下6个方面去评价其可用性: 应用性:文档是否提供相关信息？ 及时性:信息是否及时？ 准确性:信息是否正确？ 完整性:文档是否足够详细而又不会太过拘泥细节？ 可得性:文档是否随时可得？56主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的

21、编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类57 4.8 软件文档的编写技巧 1.从技术角度进行文档的编写和评价2.明确文档编写人员的责任3.让编写人员对开发项目有准确的认识4.让开发设计人员参与文档审阅工作584.8 软件文档的编写技巧1.从技术角度进行文档的编写和评价文档编制工作工不等同于一般的文字编辑工作，软件文档的内容具有很强的技术性。编制和评价软件文档应从技术角度进行把注意力集中于技术事实上594.8 软件文档的编写技巧2.明确文档编写人员的责任软件文档编写不好的一个原因是由于对它不够重视，这是由于在编写软件文档时，没有明确各种责任

22、。因此，一定要在软件文档编写的过程中明确责任。在文档加入作者以及相关人员姓名是明确责任的一种好方法。在文档中包含文档编写人员以及相关人员的姓名不仅能明确责任，还能够促进这些人员之间的交流，同时，可以明确承认他们对开发所做的工作和贡献。604.8 软件文档的编写技巧3.让编写人员对开发项目有准确的认识让文档编写人员多参加有关产品设计与开发的小组会议。让文档编写人员参与到技术要求、功能规范以及设计方案的开发工作中去。把文档编写人员包括进开发小组去。鼓励文档编写人员更多地了解有关产品背后所包含的各种技术。614.8 软件文档的编写技巧4.让开发设计人员参与文档审阅工作开发设计人员与文档编写人员一起确

23、定哪些部分必须让开发设计人员进行审阅。不要让开发设计人员从头至尾地审阅软件文档文档编写人员与开发设计人员一起利用大段的完整时间来审阅软件文档文档中与开发设计人员专业技术领域直接相关的部分绝对需要他们进行仔细审阅，剩余部分的审阅工作可以让开发小组内的其他成员完成62主要内容4.1 软件文档管理指南 4.2 软件文档的编写原则 4.3 制定文档的编写策略 建立文档的企业标准4.5 制定文档的编制计划 4.6 建立文档的编制规程 4.7 软件文档的质量要求 4.8 软件文档的编写技巧 4.9 确定软件文档类型的种类634.9 确定软件文档类型的种类 一个软件开发公司应该根据本公司开发的软件专业特点和本公司的管理能力，制定一个文件编制实施规定，说明在什么情况下应该编制哪些文件。 编制文件种类的确定国外主要有两中方法：1、求和法2、规模法644.9 确定软件文档类型的种类1