让文档敏捷起来的办法

文档，对于一个开发人员来说，总是又爱又恨。当他要维护某个软件时，能看到规范整洁、表述清楚的需求文档和设计文档时，那真是给力；可如果让他写文档时，他宁肯写上1000行代码，也不愿意写100字的文档。

如果文档的生成能够简单一点就好了。

下面是一些让文档敏捷起来的办法。

1. 成果复用

其实，在你动手开始写一篇文档之前，它的内容就已经以某种形式存在了，如果你能把已经存在的内容之间复制粘贴或者导入、自动生成文档，那你的文档岂不是瞬间就可以生成了。

这样的情况在你的身边很是常见。这里罗列出几种情况：

• 与客户的讨论记录。你和客户的讨论记录中可能就包含了某项需求的正确的定义，包含了对软件使用问题的解答……这些内容可能是一份单独的记录，也可能是以邮件形式存在，你完全可以在编写需求文档、用户手册时导入这些已有的内容。

• 已有的技术文档。软件开发必须要经过需求、设计、测试这样的过程，而后面的文档通常会继承前面文档的一些内容。比如，在任务书中规定的运行环境，它同样会出现在需求规格说明、测试计划、测试报告之中。

• 类似的历史项目文档。如果当前的项目是在历史项目上的改进，那历史项目的文档大部分内容你都可以复用。

2. 统一文档结构

为了保证文档的质量，也为了便于复用，对项目文档按类型统一文档结构是非常有必要的。对于同一类型的文档，比如需求文档，如果它具有统一的结构，那你在复用历史项目或者上一阶段的成果时，就会很省时省力。

3. 支持工具生成和检查

如果没有工具的支持，即使有文档可复用，纯靠人工，也会让人眼花缭乱，疲惫不堪。文档要敏捷起来，离不开工具。这些工具可能包括且不限于下列工具：

• 检查工具：包括语法检查工具、错别字检查工具、基于文档结构的模板符合性检查工具……

• 生成工具：基于项目管理平台生成管理文档；基于测试管理平台生成测试文档；基于测试工具生成的测试报告；基于文档比对工具生成的更改报告……

• 导入导出工具：根据文档结构导入/导出指定内容的工具。

4. 允许灵活的文档形式

文档的排版、格式的要求也挺要人命的。特别在是一些遵循GJB438B的组织中，文档的标准化常常会把那些对Word不太熟练的程序员折磨得欲仙欲死。

文档的目的是为了让相关方都能理解和知晓他该明白的内容，文档格式的标准化对于理解的帮助有那么大吗？在满足规定的文档结构之后，使用五号字和四号字会让人对文档的理解不同吗？为什么不能让文档的形式更加灵活呢？

比如，一些组织要求软件更改时要给出代码比对报告，目的就是给出文档中做了哪些更改。使用前面提到的文档比对工具可以支持生成一些html格式的比对结果报告，而组织却非得要求提供Word格式的比对报告。既然工具生成的报告已经明确地标识出了文档更改的内容，那么文档格式是html还是Word重要吗？为什么不能直接使用呢？

允许灵活的文档形式，就是不需要所有的技术文档都是Word文档，excel、html、txt、ppt等都是允许的。那些工具可以直接生成的文档，只要内容满足要求，可以不用处理直接使用。

5. 允许文档增量生成

对于一些大型的软件，它的需求文档、设计文档都不是短时间就能形成的。对于这种大型文档，应当允许它增量地生成，即需求明确了一部分，就形成一部分文档。这样也可避免大型文档由于评审时间过长，导致评审绩效变差。

还有一种情况是当软件开发迭代进行的时候，即确认一部分需求，设计实现一部分需求，验证确认一部分需求的情况下，也需要文档增量地生成。

相比于集中编写文档，增量地生成文档会更有效率。

这正是：

莫嫌文档太麻烦，其实也可变简单

抓住目标想办法，文档敏捷终实现

参考书目：知行合一：实现价值驱动的敏捷和精益开发，作者：丛斌，出版社：人民邮电出版社

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