程序员，你是否有编写软件工程文档的习惯？

          针对大多数程序员没有编写软件工程文档的习惯，专门写了一篇阐明软件工程文档重要性的文章，里面所有实例都是本人所在公司曾经发生的事情，事实上里面所提到的现象在软件工程相关领域里面都有专门的描述，本人仅将其实例化到发生在本人身边的真实情况当中。希望能给众多程序员们予一点启示。

 

我们为什么要编写软件工程文档

大家：

好！

在这里我就个人最近所做的事情做一些总结。

从 4 月 15 号完成需求分析报告到今天这段时间，我将主要精力集中在系统体系结构的分析与设计上面，原计划在今天提交一份我们项目的体系结构设计报告 ，由于存在多方面的困难，这份报告完成得有点仓促，尚需要在后面的时间中进一步补充和修正。

编写文档主要存在的困难是：

（1）    我们所正在的项目是研发项目，项目的各方面都需要相当专业的知识，因此项目的入门具有一个相当高度的门槛。

（2）    本人是在项目的中途负责项目总体框架上的把握，而在项目的早期阶段缺乏足够的相关说明文档，而编写这些相关说明文档需要相当的专业知识，只有专门负责的开发人员才有足够的能力编写这些文档。

（3）    由于团队成员之间存在着知识结构，技术背景以及思维方式上的不同，因此还未形成一个比较合理和统一的团队文化，这也造成了多方面的意见不合，如大家还未在思想意识上认同编写这些软件工程文档的重要性、迫切性及其存在的深远意义，甚至认为写这些文档纯粹是在浪费时间。因此编写文档的做法未曾得到大家普遍的认可。

缺少专业知识，我们可以去学习，因为有我们这么一支团结互助的团队，这样的困难不是不可攻克的困难；缺少早期说明资料，我们也可以去补充，因此我们软件项目的各方面都具备有专门的人才，你们相比我们新来的成员，你们对项目都有很深入的了解和体会，而且也各自具有一方面软件项目所要求的专门知识，如果你们愿意的话，你们完全有能力来编写这些所谓具有专业知识的文档；但是，如果我们还没有形成一个比较合理和统一的团队文化，如果在大部分需要合作场合里面我们不能快速地形成一致的意见，那么，其危害不仅仅是现在我们无法成功地完成软件工程相关文档。大家可以回顾一个我们团队的过去和现在，由于大家没有形成一个比较统一的思想意识，不仅在过去不断地打击我们团队的凝聚力和积极性，现在我们团队的凝聚力和积极性也在屡次遭受打击，我们可以想象，在将来，其对于我们团队顺利和健康发展的危害性，这种危害相信是我们团队中的每一个人所不愿意看到的。

我知道我们团队中的每个成员都有一种任务的使命感，尽管很多方面的意识我们需要统一，但我们都想着通过共同努力和奋斗，来完成我们共同的使命。

我个人希望本次会议能在编写文档这方统一一下大家的思想意识，说明我们完成软件工程文档这一任务的重要性和迫切性。

首先看一下我们最近发生的一些事。最近刘总为了发展我们研发部，请来了蔡老师 , 陈 老师和李老师，他们来了之后首先要做什么事呢？当然是了解我们的团队以及我们团队所正在做的事情，因此他们需要尽快融入我们的团队中，我们也需要他们尽快地融入我们的团队中。没有人希望在团队的融合上浪费太多的时间和精力。为了团队的融合我们需要做什么事情呢？交流。我们可以看到我们这段时间进行的交流，未来一段时间内还需要交流，我们也可以想象没有交流而谈团队融合的场景。可我们是如何进行交流的，或者说我们的交流工具是什么呢？口头交流。刘老师为他们大体介绍我们的团队的情况以及我们团队所在做的事情，然后他们再来深入地和我们原先团队中的每个成员逐个面对面深入的交流。好，现在请大家思考一下，我们相互之间必然存在着知识结构，技术背景以及思维方式上的不同，我们相互之间的交流是不是也必然会存在一定程度上的摩擦呢？那是不可否认的，尽管这些摩擦不至于中断我们相互之间的交流， 但我们得花费时间和精力去处理这些摩擦，摩擦越多，越大，所花费的时间和精力也会越多。所花费的这些时间和精力是否都是必要的呢？显然是不必要的。我们再思考另外一方面的问题，在交流中，对于解说人来说，他是否一次就能把自己了解的事情全部表达清楚呢？是否一次就能真正理解对方所问的问题的意图呢？是否能保证他所回答的内容就是对方所希望得到的呢？对于问问题的人来说，他是否一次就能清楚自己想要了解的全部呢？是否能够保证自己问的问题对方能顺利回答呢？对于解说人所回答的内容，他又是否一次就能全部记下来呢？是否一次就能全部理解呢？很显然，所有这些问题的答案都是否定的。我们会经常听到这样的话：“你还没完全理解我的意思！”，“我能理解你的意思，可你却不能理解我意思！”，“我没办法跟你交流了！”，“你想得太简单了！”。这样，我们可能就需要对一个同样的问题的争执进行一次又一次交流，这又将花费我们多少时间和精力呢，这些时间和精力又是否都是必要的呢？

大家应该相信，这些时间和精力的花费都不是必要的，可我们如何才能减少这些不必要的浪费呢？就是通过文档来交流。

一份好的软件项目文档，是通过多方面调查，收集，分析和总结才编写出来的，他涉及到项目的方方面面，对于新进来的成员来说，不仅能告诉他们我们曾经做了什么，如何做的，为什么那样做，也不仅能告诉他们我们现在正在做什么，如何做以及为什么要这样做，而且还能告诉他们我们将来要做什么，将会怎样做以及为什么那样做。因此通过文档，我们很容易就能让想了解我们的人尽快了解我们，想入门我们项目的人尽快入门，他们将能更加容易地融入我们的团队之中。这为我们在人力，物力，财力上带来的节约将是非常可观的。请大家想象一下，如果我们现在已经具备这些软件项目需要的文档，那么刘总将不用为了让新进来的人了解我们而花费太多的时间和精力，他递交一份文档，然后就可以做其它可能更重要的事，而新进来的人如蔡老师，陈老师和李老师需要和我们深入交谈时，我们也可以在必要的时候给他们一份相关文档，也就不用再为一个问题不断争执，他们可能不能一下子消化文档的全部内容，但也已经没有必要一下子要全部消化完了，他们完全可以在不同的时候在文档上得到他们需要的不同内容。这样我们原有团队与新进来的人之间的融合过程中，所需要的口头交流将仅定格在人与人之间（如性格）相互了解和沟通上。这无形中就为我们节约了大量的时间和精力。

其次，写文档的意义不仅在于方便了我们之间的交流，能为我们相互之间的交流节约可观的时间和精力，它也是我们团队可持续性发展的必然要求。我们所做的是软件研发，我们所研究的领域是知识密集型的高科技领域，而我们产品和主要组成部分是程序编译成的软件，由些可见我们作为软件开发工程师或算法工程师在整个团队中举足轻重的作用。如果我们团队中的软件开发工程师或算法工程师只产生代码和软件而没有产生相关文档的话，那么他所拥有的知识，技能和经验资源将永远仅停留在他的脑海中，别人也就没有办法去分享他的这些资源，这除了会带来交流与合作上的困难之外，更为严重的是他曾经以及目前所做的工作没有任何人可以轻松替代。如果有一天，这个软件开发工程师或算法工程师由于某些原因，如工作职务变动等离开了原先的工作岗位，那么我们团队将不得不浪费大量的时间和精力去做很多重复性工作，这种代价有可能是很惨重的。我们团队早期宋老师的走就是值得我们思考的一个很典型的例子。我相信我们团队之间的任何人都不愿意再看到有类似的事情发生，而防止这种类似事情发生的一种方法就是让软件开发工程师和算法工程师将自己拥有的知识，技能和经验等资源整理成文档，让大家分享。我也们可以思考一下我们人类的文明是怎么得到延续和发展的，如果没有文字的记录，很难想象我们现在所谓的人类文明会是一种什么样的境况，就我们团队发展来说，如果没有各种各样的教程和参考文献，也很难想象我们项目应该如何进展，从这方面上来说，文档的意义也就不言而喻了。

第三， 我们团队迫切需要规范化，各自的角色和职责需要明朗化，相信这是大家认同的。在软件过程领域里面经常提到“乌合之众”一词。“乌合之众”在现代汉语词典里面的解释是：一群无组织纪律的人。在软件过程领域里面其意义与之相仿，指的是由一群气味相投的人聚合到一起，未形成组织和未被管理的团队。让我们感到欣慰的是我们已经渡过了乌合之众这个阶段，因为我们已经形成了一个相对固定的组织且有相对较为稳定的协作模式。可我们也还不是正规军，因为作为正规军的很多方面的条件我们还不具备，包括人员上还有工具上的条件。但我们团队的发展目标就是形成一支具有坚实作战能力和应变能力的正规军，这个目标是坚定不移的。而文档则不但是我们作为一支正规军的必备基本装备，也是我们通向正规军道路上的奠基石，没有文档，我们的作战能力和应变能将无从谈起。回顾一下我们在 4 月初为出差重庆之前的做准备工作那段时间的那种混乱状态，纠其原因是我们事先缺乏一个整体的规划，没有做充分准备暴露的是我们作战能力的问题，突发事件太多暴露的是我们应变能力的问题。而整体规划的表现形式就是文档，没有通过文档的方式来体现，再好的再完善的规划，也难以保证顺利施行，原因很浅显，口头说明的大家都很容易忘掉，我们也不能指望通过口头说明让大家记住所有的事情。

综合地讲，写文档是我们项目团队成员之间相互交流的需要，是我们团队健康和可持续发展的必然要求，也是我们团队走向正规化的必经之路。其意义已经明显，现在大家应该相信我们并不是教条，教科书上说必须这么写我们才去写；我们写文档也不是在做花瓶，因为形式上的需要我们才写。

在形成文档规范的过程中，我们已经充分考虑了我们研发部目前的实际情况，做了很多精减和修正方面的工作。在短期内我们可能还不能看到文档所应该做出的贡献，这是因为我们文档还在整理的初期阶段，随着文档的不断修正和完善，其作用将会慢慢地显示出来。

当然形成文档不是一个人的事情，正如开头所说的，“编写这些相关说明文档需要相当的专业知识，只有专门负责的开发人员才有足够的能力编写这些文档”，因此写文档需要得到大家的多方面配合。现在我们最迫切的希望就是大家（包括公司的领导和研发部的所有成员）能从思想意识真正地重视文档的重要性，我们希望公司的领导能够将文档的编写视为我们研发部所有成员工作的一部分，并给予他们一定比例的编制文档的工作时间，我们也希望研发部的所有成员能自发地编写各方面相关文档，而不只是为了执行任务才去编写相关文档。写文档对于个人来说，的确会浪费他的工作时间和精力，但从团队和公司的全局利益出发来看，你所做的贡献将远大于你所浪费的那点时间和精力，是值得的。