让你的文档模板更有用

文档模板是GJB5000A软件过程体系的不可或缺的一个组成部分，它对整个GJB5000A软件过程体系的实施有着非常重要的作用。好的文档模板可以让项目组欣然接受，减少很多阻力；坏的文档模板只能让人生厌，项目组实施起来举步维艰。

那么，EPG怎样设计文档模板，才能使它发挥积极的作用呢？下面谈几点建议：

1. 遵循GJB438B

GJB438B中对军用软件文档的编写要求非常经典，而且经过这些年实施GJB5000A的经验来看，GJB5000A中的工程实践在GJB438B文档模板中都能找到对应的内容。比如，需求开发过程中的“制定运行方案和场景”实践，对应的就是GJB438B《需求规格说明》模板中的“3.1 要求的状态和方式”；技术解决方案过程中的“制定备选方案”和“选择备选方案”对应的就是GJB438B《软件设计说明》中的“3 CSCI级设计决策”。所以，我们的文档模板遵循GJB438B，就能够在框架上满足GJB5000A的要求。同时，作为使用度最高的军用软件标准，遵循GJB438B的文档也更容易在交付时得到最终用户的认可。

1. 坚持同样的内容在同一个文档中只出现一次的原则

技术文档非常忌讳文档的内容前后不一致，因为这样会给使用这份文档的人带来混乱。遵循GJB438B标准的文档大多可以避免这一点，只是在《软件开发计划》中要注意“5.2 软件开发环境的建立”和“7.2 项目资源”这两个章节内容的一致性。

1. 不仅要提供模板也要提供样例

要让文档模板更好用，EPG不能只是照搬GJB438B中文档的架构加上组织的技术文档格式的要求形成模板就了事，更重要的是要对文档模板中的章节内容如何编写给出样例。

就像前面提到的《软件需求规格说明》中的“3.1 要求的状态和方式”，如果只是照搬GJB438B中所要求的“标识和定义每一种状态和方式”、“将本规格说明中的需求与每一状态和方式对应起来”，可能还是有很多开发人员一脸懞，不知道如何编写。EPG需要给出编写的样例，如状态转换图、状态和需求对应的表格，这样开发人员就很清楚他们该如何做了。

1. 站在阅读者的角度设计文档

据统计文档的编写与修改次数远远小于文档被阅读的次数。而且文档编写出来不是给编写者回顾用的，更多的是为了给下游开发者使用以及在软件维护、用户操作时使用的，因此一定要站在阅读者的角度设计文档模板。比如，EPG在给出文档编写样例的时候要更多地使用图表，而不仅仅是文字。因为图表会更让人容易理解。

这正是：

文档模板不好用，影响项目的进行

4 3 8 B 要遵循，提供样例要亲民

参考书目：术以载道：软件过程改进实践指南，作者：任甲林，出版社：人民邮电出版社

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