外籍团队工作有感：4、关于文档

　　文档这玩意，大体上有着和“编码规范”类似的境遇——所有人都知道他们的重要性，但是在某些条件的约束之下，往往都是最先被抛弃的部分——我感觉到这是一件挺可悲的事情！

　　一般而言，我们会把文档分成两大块，一块是给最终用户看的，叫做“用户文档”或者“使用说明”或者“帮助文件”之类的名目。由于我目前所在的外籍团队没有完成整个项目，而且项目也是对内使用的，所以这一部分的文档工作实际上并没有展开——所以，我也就不打算对这个部分做什么分析了。或许以后有了想法再来补充吧！

　　另一部分文档是写给开发、维护、实施人员看的，通常被习惯的成为“开发文档”，这一块在国标、国军标（中国军用质量体系，和宝岛上的武装力量可真没什么关系啊）、CMM/CMMI、ISO中是被反复强调的。

　　面对如此多的标准都在强调的“开发文档”，国内的企业一般是怎么做的呢？就我个人的经历来看，大致是两种：一种是极端缺失；一种是极端严谨。前者以中小型企业为主，因为市场搏杀的残酷性，不得不放弃耗时费力而且难见成效的文档以节约成本（实际上个人感觉长期成本并没有降低）。而后者以大型企业和软件外包的发包方为主，这一点也很容易理解，大企业的管理复杂度相对更高，没有文档就很难管理和沟通；而软件外包的发包方如果没有充足的文档，则对外接口不畅甚至导致验收出现纠纷。

　　也许看到这里有人要对我拍砖了。两条极端之路往这里一摆，这不是分明在诋毁国内的开发环境么——难道国内就没有“中正平和”、“一板一眼”写开发文档的公司吗？很抱歉，就我个人经历而言，我见过的第三种情况是为了通过各种认证（比如ISO之类）而装模作样写出来的文档——这种情况似乎还不如前两种极端路线！也许是我的工作经历还不够丰富吧，反正我只见过这么三种，如果有哪位同仁在这方面有丰富经验的，不妨跟帖深入讨论一下！

　　说了半天国内的，该说一说目前我所在的外籍团队的文档观念了。这个团队采用的是Scrum开发模式，这是敏捷是开发的一种。对于敏捷开发，目前国内最广为流传的一种说法是“敏捷开发不重视文档”，甚至流传着“敏捷开发不写文档”的说法，这是真的吗？

　　关于敏捷开发，我打算另开一个小节来介绍我的体验和理解。不过在此，我还是想对不熟悉敏捷开发的同仁稍微介绍一下敏捷开发的两个重要“价值观”（不是敏捷开发价值观的全部，仅抽取与本话题相关的两条）：

• 人和交互 重于过程和工具。
• 可以工作的软件 重于求全责备的文档。

　　好了，现在暂时先不深究这两条敏捷开发价值观的具体内涵和外延，回到我们的文档话题上来（稍候马上会说明其中的联系）。软件开发文档通常会在三种场合下产生作用：

1. 　　项目开发/实施/维护人员之间进行交流使用；
2. 　　与客户/最终用户进行交流
3. 　　在项目移交/维护中提供指导

　　对于第一种情况，简而言之，其实就是团队成员之间的沟通。现在回过头看看上面刚刚提到的敏捷开发的价值观，有没有发现什么？由于强调的人交互，所以我们通常可以结对编程，两人一组直接口头沟通，也可以直接和PO（Project Onwer）去讨论功能细节。既然我们可以口头地、便捷地直接沟通，为什么还需要文档呢？另一方面，由于之前曾经提到过的，大家采用了严谨的编码规范和命名规则，代码本身就可以充分的说明自己的作用和含义了，再加一份文档又有多少作用呢？

　　所以，在团队内部沟通顺畅的情况下，编写文档的工时确实可以被节约下来——这也就是业内传说的“敏捷开发不写文档”的缘故吧！

　　但是万事没有绝对，比如团队之间需要分享一些信息，比如图片或者链接地址之类的，口头沟通是相当不灵光的！所以，我们的团队，其实是写文档的！不过和国内的形式稍有不同罢了。按老外的说法，他们会为每一个team建一个wiki网站，每个人都可以上去自己随意写各种东西。这种技术wiki有时候被翻译成“IT团队知识库”，目前国内有一些团队已经这么做了，所以很容易的在网上搜索得到。不过由于某种原因，我们的团队并没有建自己的wiki，而是采用了更加奇怪（但是简单）的手法——我们在局域网中建了一个共享目录，写了一个Office OneNote笔记本文件，所有人直接打开这个文件往里面写东西就好了。

　　我们充当Wiki的oneNote被叫做“知识库”，我觉得稍有不妥。有个很有意思的小插曲，欧洲杯有一场瑞典对乌克兰的比赛，然后就外籍同事PS了一张瑞典同事和乌克兰同事各持国旗/标语的大海报，提示我们去看某日的比赛时间，然后又有其他同事把自己喜欢的球员照片贴在旁边，颇为有趣。

　　上述wiki式的文档，仅仅作为团队内部沟通使用是没有什么问题的，不过用于和客户/用户沟通则实在不够严肃。上面提到文档的第二个适用场合就是和客户/用户进行交流。不过换个思路想一想，按照国家标准或者行业标准，拿着技术文档去和客户交流，会是一件舒服的事情吗？估计业界的同仁对此都曾经有过不愉快的经验吧！在任何一个国家都普遍存在用户不懂技术的情况，所以即使用了文档或者UML图之类的东西，效果也不见得会很好。

　　在这个方面，我们的外籍团队是怎么做的呢？这里是一个在线文档管理系统（http://www.rallydev.com/），可以免费试用，所以一看便知。我们会让客户（由于我们是做内部开发，所以客户其实就是其他部门的同事）把他们想要的东西一条一条写出来，并且描述清楚，再让客户自己排出优先级，在开发过程中逐步沟通。这个在线文档系统，就是我们的项目需求文档了。另外，还有一些简单易用的界面原型程序（不是在线程序，大家自行想象吧，就是个专门画界面的画图板），可以让客户轻易的画出他们想要的程序界面，然后我们照着他们提的要求去做就行了。

　　最后一个文档发挥作用的重要场合就是项目移交和维护。比如我把项目交接给另一组维护团队，他们进行bug维护以及后续开发时，往往需要知道我们的设计思路以及每个功能的作用。对我们目前的团队而言，还没有发生过移交的情况，不过我觉得这种情况发生的时候会是什么情形应该不难估计。由于遵循着严格的编码规范，所以代码本身就可以说明自己是做什么的，因此维护人员不会费太大的力气就能弄明白具体功能。而整体结构（有人也喜欢叫做架构）的理解，就需要借助于另一种代码了——自动测试代码——我们的每一项（完整）功能都需要编写集成测试（做开发的同仁应该都知道这是什么吧！），集成测试一般都是编写成测试脚本进行自动化测试的，所以想要理解一个程序的功能，只需要去读他的集成测试方法就行了，集成测试项目基本上可以看做是整个项目源码的目录。当然，这是专业技术活，没有必要详细介绍了，看代码的本领相信各位同仁应该都有吧！

　　小结一下：我们的外籍团队采用了wiki（我们用OneNote替代）、在线需求管理程序、界面原型画图程序、集成测试源代码，以及（严格符合编码规范的）程序源码来充当文档，分别可以解决团队内沟通、与客户沟通、与移交团队沟通的几种典型场合。

　　那么这么做有什么好处，或者说与国内那3种“写文档”的方式又有什么区别呢？

　　首先，我们没有长篇累牍的公式化文档模板。我估计，大量公式化模板是国内同仁痛恨写文档的重要原因（没有之一）。公式化文档模板的最大坏处就在于臃肿、不知所云，写了不知道给谁看，也不知道要写什么。所以老外的敏捷式开发就把这些乱七八糟的玩意全扔了（话说回来啊，这些格式化模板其实不也是老外们发明的嘛），只做必须的文档，不做无意义的文档。

　　另外，国内有很多专精于文档的大公司正在为文档与代码同步的问题头痛不已。因为一旦文档改了，对应的代码就要改——这个还比较容易做到；而由于修正bug、添加新功能等原因修改了源码，又要返回去维护文档，保持同步——这个做起来就不舒服了。而一旦文档与代码没有保持完美同步，那文档就失去了指导意义，变成垃圾了。所以现在我们的外籍团队（实际上是敏捷式开发）强调可以工作的软件 重于求全责备的文档，让（编码规范的）代码自己解释自己，就不必担心代码与文档重复、而且难以保持同步的问题了。

　　当然，我个人觉得这并不是什么定式。比如软件外包的发包公司，他们一定会坚持要让文档尽善尽美的“臃肿”下去的，不然~~呵呵，承包方偷工减料会有合同纠纷吧！

　　再者，拥有复杂的文档体系之后，往往会需要对文档有审核以及文档的版本进行控制，这些工作无疑会消耗极大的工作量。而这些工作往往是由管理人员来完成的——国内一个糟糕的现状是：管理人员普遍不太懂技术，这样也容易造成公司内部的内耗加大。而目前我们的文档根据沟通目标不同，分别由技术人员和管理人员各自维护自己擅长的部分，可以进一步降低内耗。我觉得是个不错的管理方式。、

 

　　总结一下：文档不是可有可无的，外籍团队带来的文档观让我非常欣赏。国内的文档观（普遍而言）大致还停留在欧美90年代左右的水准，国内和国外差的，不是技术，而是视野——眼界开阔了，果然很多东西就不一样了——至少若干年前我在成堆的国标、CMM文档里苦战的时候，真的不知道自己在写什么、为什么而写、写给谁看！

2012-05-23 23:02:33

 

2012-05-24 13:27:57 修改错别字，“继承测试”应为“集成测试”

转载于:https://www.cnblogs.com/michaelyu/archive/2012/05/23/2515481.html