Martin对敏捷宣言中“可工作软件胜过面面俱到文档”的解释

Martin对敏捷宣言中“可工作软件胜过面面俱到文档”的解释

没有文档的软件是一种灾难。代码不是传达系统原理和结构的理想媒介。团队更需要编制易于阅读的文档，来对系统及其设计决策的依据进行描述。

 

 

然而，过多的文档比过少的文档更糟。编制众多的文档需要花费大量的时间，并且要使这些文档和代码保持同步，就要花费更多的时间。如果文档和代码之间失去同步，那么文档就会变成庞大的、复杂的谎言，会造成重大的误导。

 

 

对于团队来说，编写并维护一份系统原理和结构方面的文档将总是一个好主意，但是那份文档应该是短小的（short）并且主题突出的（salient）。“短小的”意思是说，最多有一二十页。“主题突出的”意思是说，应该仅论述系统的高层结构和概括的设计原理。

 

 

如果全部拥有的仅仅是一份简短的系统原理和结构方面的文档，那么如何来培训新的团队成员，使他们能够从事与系统相关的工作呢？我们会非常密切地和他们在一起工作。我们紧挨着他们坐下来帮助他们，把我们的知识传授给他们。我们通过近距离的培训和交互使他们成为团队的一部分。

 

 

在 给新的团队成员传授知识方面，最好的两份文档是代码和团队。代码真实地表达了它所做的事情。虽然从代码中提取系统的原理和结构信息可能是困难的，但是代码 是惟一没有二义性的信息源。在团队成员的头脑中，保存着时常变化的系统的脉络图（road map）。人和人之间的交互是把这份脉络图传授给他人的最快、最有效的方式。

 

 

许多团队因为注重文档而非软件，导致进度拖延。这常常是一个致命的缺陷。有一个叫做“Martin文档第一定律（Martin’s first law of document）”的简单规则可以预防该缺陷的发生：

直到迫切需要并且意义重大时，才来编制文档。

 

 

摘自：Robert C. Martin《敏捷软件开发：原则、模式与实践》

 

评论

4 楼 windshome 2013-07-19  

谢谢袁老师的回复。以我从事设计开发十五年的工作经历来看，因为自己近十年从事的行业比较特殊，因此，在使用敏捷时，也和常见的敏捷有很大区别。


通常，我从事的行业，对产品概念完整性的要求非常非常高，使用小版本迭代，很大可能第二个版本发现要顺利进行，要推翻第一个迭代的很多东西（第一个迭代的很多东西需要推翻重写），而且这种情况随着开发活动的进展会越来越多，越来越频繁。


为了解决这样的问题，会衍生出一个非常庞大的sprint0。在这个sprint0里，其实不是敏捷方式来做的（不过这也不怎么要紧）。

再演变，可能会演变成另外一种场景，产品的第一个版本，不采用敏捷方式，而是传统方式来做，最重要的是，澄清和反复确认产品的最最精髓部分（一般产品的精髓和本质，是一组相互关联的概念）和架构（相当于人体的骨骼），然后在实现过程中，不断完善概念和架构。

因为概念的变化实际上是比较缓慢的，架构变化稍多一些，实现随着形势的发展，变化最多。所以第一个版本之后，基本上概念不大会变化了，架构也不大会进行伤筋动骨的改变，大多数时候，是一些实现上的调整，增加功能、功能变化。从此之后，倒是可以使用敏捷开发，来很大程度上提高产品的开发效率，提高产品质量。

或者说，第一个版本不能图快，要稳打稳扎，要打下一个扩展和改进的很好的基础（倒是无需考虑太多，只是打下一个清楚的底子非常重要）；后续的改进等等可以制定快速反应、快速发布的策略。第一个版本图快了，后面的改进势必变慢，或者把产品变成技术的简单堆砌，一锅大杂烩。

3 楼 袁斌_AgileDo 2013-07-19  

windshome 写道

袁老师，刚听过了您的课，对这一篇说点自己的理解：

许多团队因为注重文档而非软件，导致进度拖延。这常常是一个致命的缺陷。

这个现象估计国外有这种情况，国内通常都是文档不足，这是我见到的情况。当然还有一种情况就是文档描述不清晰，太多歧义；再有就是文档和实际的工作两张皮（其实就是无意义无价值的文档太多）。

所以在国内的软件开发这个行业，我的感觉还是严格要求文档，不是要求写多少文档，而是要求用文档在设计开发过程中起到Brooks博士的那句“提纲挈领”的作用。

同意！严格要求可以“提纲挈领”的文档

2 楼 windshome 2013-07-03  

袁老师，刚听过了您的课，对这一篇说点自己的理解：

许多团队因为注重文档而非软件，导致进度拖延。这常常是一个致命的缺陷。

这个现象估计国外有这种情况，国内通常都是文档不足，这是我见到的情况。当然还有一种情况就是文档描述不清晰，太多歧义；再有就是文档和实际的工作两张皮（其实就是无意义无价值的文档太多）。

所以在国内的软件开发这个行业，我的感觉还是严格要求文档，不是要求写多少文档，而是要求用文档在设计开发过程中起到Brooks博士的那句“提纲挈领”的作用。

1 楼 windshome 2013-07-03  

袁老师，刚听过了您的课，对这一篇说点自己的理解：

许多团队因为注重文档而非软件，导致进度拖延。这常常是一个致命的缺陷。

这个现象估计国外有这种情况，国内通常都是文档不足，这是我见到的情况。当然还有一种情况就是文档描述不清晰，太多歧义；再有就是文档和实际的工作两张皮（其实就是无意义无价值的文档太多）。

所以在国内的软件开发这个行业，我的感觉还是严格要求文档，不是要求写多少文档，而是要求用文档在设计开发过程中起到Brooks博士的那句“提纲挈领”的作用。