如何制订出好用的文档模板?

对于实施GJB5000的组织来说,要建立一套本地化的、可操作的、符合标准的软件过程管理体系,就少不了要制定出一套好用的、可用的工作产品模板。那么,如何制定出一套好用的文档模板呢?

制定文档模板,需要了解模板的构成。模板、指南和示例,是构成模板的三要素。要制定出好用的文档模板,就要从这三方面来下功夫。

  1. 模板

这里所说的模板,指的是文档的组织结构,它决定了文档表述的内容以及行文顺序。实际上已经有很多国际、国内的标准对不同类型的文档给出了编写内容和组织结构的要求,对于实施GJB5000的组织来说,可以参考GJB438C/GJB438B标准,在其基础之上,考虑管理需要,来制定适合组织自己的文档模板。

比如:如果没有合适的用于描述软件配置项用户需求的文档,可以参考GJB438B的《软件研制任务书》来制定软件配置项用户需求文档模板,并且根据需要,在这个任务书模板中增加“需求可追踪性”章节,以建立软件配置项用户需求与系统需求之间的需求双向追溯。

  1. 指南

在文档模板中仅仅提出编写内容的要求还是不够的,还要让使用者知道每个章节的内容应当何时写、写什么和怎么写,这就是指南的意义。

这三个方面也是指南的三个主要内容:

  • 理由。说明该章节为什么需要写,应该什么时机写。比如,《需求规格说明》中要求定义需求的优先顺序和关键性,是因为当软件存在多个构建版本,需要分批次实现和交付软件,就需要确定需求的优先顺序,以免给交付带来困扰;而定义需求的关键性,一方面可以为需求的优先顺序提供参考,另一方面也可以在工期紧张的情况下,能够优先保证关键性需求得到实现和确认。要编写这些内容,需要先确定用户交付需求、外部接口匹配需求,以及对功能、质量特性需求已经有了清晰定义。

  • 内容。说明该章节应写的内容。比如,对于描述需求的优先顺序来说,应当列出所有可实现需求实现的高、中、低的优先顺序。

  • 工具。说明作者编写该章节可利用的模板、工具、分类、提示等信息。比如,对于描述需求的优先顺序来说,可以直接给出一个模板:

需求名称 优先级
XX需求
YY需求
  1. 示例

在模板中除了指南之外,还应给出一些实际项目的示例,以便于使用者更好地理解如何编写文档的各部分内容。

比如,将指南中给出的模板以组织内实际项目的需求列出来。

总之,通过贯彻模板的三要素,可以帮助组织建立出一套好用的文档模板。

这正是:

如何制定好模板,模板要素先了解

模板指南和示例,做好就有好模板

参考书目:软件需求最佳实践,作者:徐锋,出版社:电子工业出版社

作者简介:王小双,长期从事GJB5000推广、实施、评价、改进的工作,创建《软件工程之思》微信公众号,一直在《软件工程之思》分享GJB5000、CMMI、软件工程的知识和感悟。现致力于GJB5000咨询以及软件过程改进、软件工程能力提升的研究工作。

如何制订出好用的文档模板?》来自互联网,仅为收藏学习,如侵权请联系删除。本文URL:https://www.hashtobe.com/732.html