软件工程开发文档写作教程(01)—开发文档的意义与作用

---

版权声明

• 本文原创作者：谷哥的小弟
• 作者博客地址：http://blog.csdn.net/lfdfhl
• 本文参考资料：电子工业出版社《软件文档写作教程》 马平，黄冬梅编著

---

软件工程开发文档的意义

软件文档是整个软件开发工作的基础，现代工程化的软件开发离不开软件文档。软件文档体系的建立与软件开发阶段密切相关，是软件开发整个生命周期中必不可少的一部分，软件生命周期始于软件文档，软件文档贯穿着整个软件生命周期。

从软件开发方来看，由于现在软件系统的规模越来越大，一般已经不是一个人或者几个人的小团队能够独立完成的系统，随着系统复杂程度的不同，开发人数从一个到几千个。当人数增多到一定程度的时候，沟通所带来的时空成本都将成指数倍地增长，并且最终将不可收缩。而且现在的软件系统的开发通常不是由单纯的一个团队来完成的，一个大的系统往往被分成若干个小系统，由不同的开发团队来完成。从时间上来看，一个大的系统可能由某个团队承担设计工作，另一个团队承担编码，再由另一个团队完成测试工作。系统如何分割，如何把子系统的要求表达清楚，这些问题如果只是依赖简单的口头说明，也许在开始的一段时间内是可以记住 的，但是随着时间的增长，记忆开始遗忘，这样的开发模式更增加了开发者之间的沟通难度。

软件工程开发文档(document)正是描述系统功能，刻画子系统间的相互关系，提供给开发者的精确、完整的指导资料。软件文档是软件开发者之间的沟通渠道，是具体工作的安排表，是系统的开发标准。

软件文档是软件产品的伴生物，记录着软件产品从诞生之前到开发完成整个过程的 相关信息，它具有固定不变的形式，可被人和计算机阅读。它和计算机程序共同构成了能 完成特定功能的计算机软件。传统的硬件产品及其产品资料在整个生产过程中都是有形可 见的，但是软件生产则有很大不同，软件文档本身就是软件产品的一部分。没有软件文档的软件，不成其为软件更谈不到软件产品。没有软件文档的软件是不利于推广、不可维 护、无法重用的。

软件工程开发文档的作用

软件文档的本质作用是桥梁，是纽带，连接着软件开发方、管理人员、用户以及计 算机，将其构成一个相互影响相互作用的整体。软件开发人员在各个阶段中以软件文档作为前阶段工作成果的体现和后阶段工作的依据，这个作用是显而易见的。软件开发过程中 软件开发人员需制定一些工作计划或工作报告，这些计划和报告都要提供给管理人员，并得到必要的支持。管理人员则可通过这些软件文档了解软件开发项目安排、进度、资源使用和成果等。软件开发人员需为用户了解软件的使用、操作和维护提供详细的资料，这被称为用户文档。

在软件工程中，文档用来表示对需求、工程或结果进行描述、定义、规定、报告或 认证的任何文字或图示的信息。它们描述和规定了软件设计和实现的细节，说明使用软件的操作命令。文档也是软件产品的一部分，没有文档的软件就不成为软件。软件文档的编 制在软件开发过程中占有突出的地位和相当大的工作量。高质量文档对于转让、变更、修改、扩充和使用文档，对于发挥软件产品的效益有着重要的意义。

软件文档的最主要目标是传达一个系统的技术要素和使用方法。第二个目标是提供 软件开发过程中的需求，决策，行为，角色和责任的书面记录。只有实现了这两个目标， 软件文档才真正提供了有意义的信息。

软件开发人员在各个阶段中以文档作为前阶段工作成果的体现和后阶段工作的依 据，这个作用是显而易见的。软件开发过程中软件开发人员需制定一些工作计划或工作报 告，这些计划和报告都要提供给管理人员，并得到必要的支持。管理人员则可通过这些文档了解软件开发项目安排、进度、资源使用和成果等。软件开发人员需为用户了解软件的使用、操作和维护提供详细的资料，我们称此为用户文档。以上三种文档构成了软件文档的主要部分。

企业现状的积弊

令人痛心的是部分电子信息企业对于软件开发文档相关的工作较为漠视，主要原因如下：

• 1、优先考虑代码功能：在某些软件公司中，开发速度和产品功能被视为最重要的，其他方面（如文档编写）则被认为是次要的。因此，开发人员可能会集中精力于代码编写和测试，而忽略文档编写。

• 2、文档陈旧过时：有些软件公司认为文档编写非常重要，但由于软件产品的迭代速度很快，旧版本的文档往往很快就过时了。因此，它们可能会把更多的时间和精力投入到更新的产品开发上，而不是更新文档。

• 3、视为浪费时间：一些软件公司可能认为，编写详细的文档需要花费大量的时间和资源，而这些资源可以用于编写更多的代码或促进产品的推广和销售，从而更好地满足客户需求。

但是无论是什么原因，完全忽略文档编写可能会对软件开发团队的效率和产品质量造成负面影响。因此，开发人员应该意识到文档编写的重要性，并尽可能为他们的代码撰写清晰、详细的文档，以帮助未来的开发人员更好地理解和修改软件系统。