小议scrum - 撤销设计文档
小议scrum - 取消设计文档？
我不懂scrum。最近浏览JavaEye的帖子，越来越多的scrum字眼撞入了眼球，于是开始关注它、学习它。《Scrum敏捷项目管理》由Scrum的缔造者Ken Schwaber撰写，算是Scrum相关的一本经典作品。书中确实总结了一些有效的敏捷方法，但阅读过程中也有一些疑惑。标题中提到的这个观点是我遇到的其中一个。
在该书中文版第109页中写到：
看到这里，我吃了一惊。取消设计文档？真的要颠覆传统吗？我知道开放的、面对面的交流很重要：大家能够从不同的角度评价问题，有利于全面地权衡解决方案的优劣；同时集中式讨论有助于迅速地发现问题，集体的智慧也提供了更快找到解决方案、找到更优解决方案的可能。但是，仅仅通过面对面的交流就够了吗？我有几点疑惑：
一、以这样的方式得到的解决方案肯定就是最优的方案吗？
二、解决方案肯定不会存在漏洞了吗？
三、解决方案在未来不可能扩展或改变吗？
四、过了一段时间后，大家仍能清晰地记得当初的解决方案吗？
如果以上疑惑中至少有一个是问题，我们该如何解决呢？把面对面的交流成果以书面的方式保存下来（比如写成设计文档），我们不用担心遗忘，我们可以冷静地重新审视方案，每位参与交流的成员都有机会知道自己的理解与团队的理解（在文档中反映）是否一致。如果不这样，我们得用什么方式来应对这些可能的问题呢？这些方式的代价会（比以书面的方式保存下来）低一些吗？
我知道一些朋友会提到一个观点：好的代码就是文档，或者类似的说法。但是代码不能代替文档，因为：一、与文档相比，代码与人类的普通逻辑思维差异甚大。二、因为第一点，代码只适合程序员阅读，而文档的适应范围更广。三、代码通常是散布的（比如一项使用Java开发的Web应用解决方案就可能涉及到数据库、用Java编写的组件及页面），而文档可以把这些内容组织为一个便于理解的整体。
或许还有朋友会提到：文档很难维护，容易过时，特别是设计文档。没错！代码最终是要转换成可运行的程序，并在交付给客户之前进行测试和验证。如果发现问题，代码必须修正。在这种外在的动力下，代码最终会与产品目标达到一致。但文档（特别是不需要交付给客户的文档，其中最特别的是主要由程序员使用的设计文档），在没有外在动力的情况下很可能不被维护而迅速过时、失效。在一次性的项目中（我的意思是指项目的产品仅用于某个特定的客户，后期的维护时间很短或维护内容不太复杂，团队也不需要在该项目的开发过程中积累更多的知识），文档失效可能并不是最突出的问题。此外，我个人有种感觉：找到代码写得很烂的程序员很容易，但找到文档写得很烂的程序员更容易！这或许得部分归咎于我们的教育吧？不管怎样，我始终认为文档的问题是一个管理上的问题，文档本身没有错。团队要生产好的代码，也要生产好的文档。
这两天在Scrum Alliance的网站上看到一篇访谈：Scrum Meets Waterfall - An Interview with Mike Cohn (http://www.scrumalliance.org/articles/93-scrum-meets-waterfall)。Mike是Scrum Alliance的奠基人之一。在文中Mike提到：
看到这里，我想，这可以理解为对书中的那段话的一个修正吧。或许对于那句话我应该理解为，作者只是想在Service1st这个团队中取消设计文档？
猫咪说的这些东西确实蛮有道理的
后补文档非常耗费时间，可是很多项目都是如此。
而且项目经理在项目结束后就去负责其他项目了，这个项目的后补的文档也很少有人关注质量，补上就行的做法让文档毫无意义可言。
我不懂scrum。最近浏览JavaEye的帖子，越来越多的scrum字眼撞入了眼球，于是开始关注它、学习它。《Scrum敏捷项目管理》由Scrum的缔造者Ken Schwaber撰写，算是Scrum相关的一本经典作品。书中确实总结了一些有效的敏捷方法，但阅读过程中也有一些疑惑。标题中提到的这个观点是我遇到的其中一个。
在该书中文版第109页中写到：
引用
我与（Service1st团队的）哈尔及经理们探讨优化团队绩效的最重要因素。……我还建议取消开发过程中仅支持瀑布式方法的人工因素，比如设计文档等。Scrum依赖高密度、面对面的交流和团队合作；……
看到这里，我吃了一惊。取消设计文档？真的要颠覆传统吗？我知道开放的、面对面的交流很重要：大家能够从不同的角度评价问题，有利于全面地权衡解决方案的优劣；同时集中式讨论有助于迅速地发现问题，集体的智慧也提供了更快找到解决方案、找到更优解决方案的可能。但是，仅仅通过面对面的交流就够了吗？我有几点疑惑：
一、以这样的方式得到的解决方案肯定就是最优的方案吗？
二、解决方案肯定不会存在漏洞了吗？
三、解决方案在未来不可能扩展或改变吗？
四、过了一段时间后，大家仍能清晰地记得当初的解决方案吗？
如果以上疑惑中至少有一个是问题，我们该如何解决呢？把面对面的交流成果以书面的方式保存下来（比如写成设计文档），我们不用担心遗忘，我们可以冷静地重新审视方案，每位参与交流的成员都有机会知道自己的理解与团队的理解（在文档中反映）是否一致。如果不这样，我们得用什么方式来应对这些可能的问题呢？这些方式的代价会（比以书面的方式保存下来）低一些吗？
我知道一些朋友会提到一个观点：好的代码就是文档，或者类似的说法。但是代码不能代替文档，因为：一、与文档相比，代码与人类的普通逻辑思维差异甚大。二、因为第一点，代码只适合程序员阅读，而文档的适应范围更广。三、代码通常是散布的（比如一项使用Java开发的Web应用解决方案就可能涉及到数据库、用Java编写的组件及页面），而文档可以把这些内容组织为一个便于理解的整体。
或许还有朋友会提到：文档很难维护，容易过时，特别是设计文档。没错！代码最终是要转换成可运行的程序，并在交付给客户之前进行测试和验证。如果发现问题，代码必须修正。在这种外在的动力下，代码最终会与产品目标达到一致。但文档（特别是不需要交付给客户的文档，其中最特别的是主要由程序员使用的设计文档），在没有外在动力的情况下很可能不被维护而迅速过时、失效。在一次性的项目中（我的意思是指项目的产品仅用于某个特定的客户，后期的维护时间很短或维护内容不太复杂，团队也不需要在该项目的开发过程中积累更多的知识），文档失效可能并不是最突出的问题。此外，我个人有种感觉：找到代码写得很烂的程序员很容易，但找到文档写得很烂的程序员更容易！这或许得部分归咎于我们的教育吧？不管怎样，我始终认为文档的问题是一个管理上的问题，文档本身没有错。团队要生产好的代码，也要生产好的文档。
这两天在Scrum Alliance的网站上看到一篇访谈：Scrum Meets Waterfall - An Interview with Mike Cohn (http://www.scrumalliance.org/articles/93-scrum-meets-waterfall)。Mike是Scrum Alliance的奠基人之一。在文中Mike提到：
引用
There are a lot of myths in agile about things like, you know, “documentation is horrible.” Documentation is not horrible, right? The Agile Manifesto says we value working software over comprehensive documentation. It doesn’t say get rid of all documentation. And a lot of agilists are opposed to Gantt charts and things like that. Those are mistakes. Gantt charts are wonderful communication tools. So I don’t go in and want to try to change how a, how a company looks at things.
看到这里，我想，这可以理解为对书中的那段话的一个修正吧。或许对于那句话我应该理解为，作者只是想在Service1st这个团队中取消设计文档？
1 楼
魔力猫咪
2008-06-04
XP之类的敏捷开发提出的消灭文档主要是消灭那些过度的文档。重要的组件的设计还是要有文档留下来的。不过敏捷开发更看重代码。你问这个组件如何运行？那好，执行一下单元测试，然后再看看代码就可以了。单元测试明确地告诉了你这个组件是如何工作的。
你要是把所有的对象调用都用UML表现出来，再加上大量的描述。你一个从页面到数据库的简单对象CRUD也要写上十几页。
敏捷开发的Grails一个命令建领域模型，修改好后再自动生产脚手架，最后你修改一下脚手架就可以先跑起来了。20分钟都没有。
你文档+编码得两天（文档写得不够好的话还得多次修改，时间更多），黄花菜都凉了。
还有就是敏捷开发要求结对编程、技术在团队中流转。只要项目人员不是一下就全走了，那么团队就一直能保持对项目的了解。不会因为一个设计师跑了，大家干什么都不知道了。你加入一个敏捷团队，很容易从老队员那里知道各个组件的使用。
以为靠设计文档(即使是完全及时，且全面)，可以随便找几个人，熟悉几天就能干活的，都是白痴。
你要是把所有的对象调用都用UML表现出来，再加上大量的描述。你一个从页面到数据库的简单对象CRUD也要写上十几页。
敏捷开发的Grails一个命令建领域模型，修改好后再自动生产脚手架，最后你修改一下脚手架就可以先跑起来了。20分钟都没有。
你文档+编码得两天（文档写得不够好的话还得多次修改，时间更多），黄花菜都凉了。
还有就是敏捷开发要求结对编程、技术在团队中流转。只要项目人员不是一下就全走了，那么团队就一直能保持对项目的了解。不会因为一个设计师跑了，大家干什么都不知道了。你加入一个敏捷团队，很容易从老队员那里知道各个组件的使用。
以为靠设计文档(即使是完全及时，且全面)，可以随便找几个人，熟悉几天就能干活的，都是白痴。
2 楼
hantsy
2008-06-05
很多公司，文档都是流于形式，写文档为了套格式或者公司制定的什么狗屁文档规范（当然有时候也是公司设计人员或项目经理工作业绩或表现的一部分），其内容可以去掉十之八九，更可笑的，很多文档都是事后补的。。。
文档作为开发的辅助方式，对开发起到必要的说明作用，敏捷只要必要的文档就够了。
文档作为开发的辅助方式，对开发起到必要的说明作用，敏捷只要必要的文档就够了。
3 楼
movingboy
2008-06-05
魔力猫咪 写道
XP之类的敏捷开发提出的消灭文档主要是消灭那些过度的文档。重要的组件的设计还是要有文档留下来的。不过敏捷开发更看重代码。你问这个组件如何运行？那好，执行一下单元测试，然后再看看代码就可以了。单元测试明确地告诉了你这个组件是如何工作的。
你要是把所有的对象调用都用UML表现出来，再加上大量的描述。你一个从页面到数据库的简单对象CRUD也要写上十几页。
敏捷开发的Grails一个命令建领域模型，修改好后再自动生产脚手架，最后你修改一下脚手架就可以先跑起来了。20分钟都没有。
你文档+编码得两天（文档写得不够好的话还得多次修改，时间更多），黄花菜都凉了。
还有就是敏捷开发要求结对编程、技术在团队中流转。只要项目人员不是一下就全走了，那么团队就一直能保持对项目的了解。不会因为一个设计师跑了，大家干什么都不知道了。你加入一个敏捷团队，很容易从老队员那里知道各个组件的使用。
以为靠设计文档(即使是完全及时，且全面)，可以随便找几个人，熟悉几天就能干活的，都是白痴。
你要是把所有的对象调用都用UML表现出来，再加上大量的描述。你一个从页面到数据库的简单对象CRUD也要写上十几页。
敏捷开发的Grails一个命令建领域模型，修改好后再自动生产脚手架，最后你修改一下脚手架就可以先跑起来了。20分钟都没有。
你文档+编码得两天（文档写得不够好的话还得多次修改，时间更多），黄花菜都凉了。
还有就是敏捷开发要求结对编程、技术在团队中流转。只要项目人员不是一下就全走了，那么团队就一直能保持对项目的了解。不会因为一个设计师跑了，大家干什么都不知道了。你加入一个敏捷团队，很容易从老队员那里知道各个组件的使用。
以为靠设计文档(即使是完全及时，且全面)，可以随便找几个人，熟悉几天就能干活的，都是白痴。
猫咪说的这些东西确实蛮有道理的
4 楼
TopspeeD
2008-06-13
hantsy 写道
很多公司，文档都是流于形式，写文档为了套格式或者公司制定的什么狗屁文档规范（当然有时候也是公司设计人员或项目经理工作业绩或表现的一部分），其内容可以去掉十之八九，更可笑的，很多文档都是事后补的。。。
文档作为开发的辅助方式，对开发起到必要的说明作用，敏捷只要必要的文档就够了。
文档作为开发的辅助方式，对开发起到必要的说明作用，敏捷只要必要的文档就够了。
后补文档非常耗费时间，可是很多项目都是如此。
而且项目经理在项目结束后就去负责其他项目了，这个项目的后补的文档也很少有人关注质量，补上就行的做法让文档毫无意义可言。
5 楼
fly_bluewolf
2008-06-13
注意是取消设计文档，而不是系统架构文档，接口说明文档。我个人认为那些详细的设计文档在开发工程中很累赘，看这些文档还不如直接看代码。我的习惯是在关键代码，不易弄清楚的代码部分加上注释。
另外scrum建议取消设计文档，很大部分原因是因为有Unit test，如果不知道某个函数不知道怎么使用，直接看Unit test好了，这是最好的文档。
另外scrum建议取消设计文档，很大部分原因是因为有Unit test，如果不知道某个函数不知道怎么使用，直接看Unit test好了，这是最好的文档。