敏捷宣言二解读：可以工作的软件胜过完备的文档&实践思考

一.敏捷宣言二解读：可以工作的软件胜过完备的文档

糟粕所传非粹美，丹青难写是精神

传统的软件开发过程对文档的要求往往达到变态的程度：每个方面、每个阶段都需要大量的文档，每份文档都要求非常详尽，每份文档都要经过多次评审-修改循环。大量的时间和精力耗费在文档上面。大家都习以为常，没人想到过要改变。

文档的主要作用是作为沟通的工具，把一个人的想法、意图以及关于软件产品的知识传达给另外的人。至少从这一点来说，文档是有用的。问题不是要不要文档，而是与可工作的软件相比，文档有多重要？谁是主谁是仆？不能买椟还珠，恶紫夺朱。胎盘的作用是为胎儿提供营养，一旦婴儿生出来，胎盘就该丢弃了；脚手架的作用是辅助建造房子，房子建好之后，脚手架就应该拆除。Martin Fowler等人主张将UML写在咖啡杯垫纸上，其含义是：UML等文档不用那么严肃，应该是两个人在喝咖啡的时候沟通讨论，在咖啡杯垫上写写画画，一旦取得共识，就把它丢弃。不要写一个精美完备到你舍不得丢弃的文档，不要把盒子造得比它用来装的珍珠还贵重。

首先，从沟通的有效性来说，文档的效果差不多是最差的。

最有效的沟通方式是面对面沟通，其次是视频会议（假设带宽够大，视野够广），再其次是电话，再其次是QQ等即时通讯工具，最后才是正式文档和email等等。文档是单向的，它不能回答未预期的问题。我们不需要像录音机那样的单向播放，我们需要跟作者循环往复的交流，这样才能把问题搞深搞透。

其次，从完备性的方面来说，文档只是对软件的片面的反映。

不管你对软件的描述多么丰富，都不可能达到软件本身那么详细。有这么一个寓言：某人很歆慕琴师的高超技艺，请琴师描述一下琴曲的美好之处，琴师二话不说，直接给他弹了一曲。某人说我听完了，请你描述一下它的美好之处。琴师二话不说，重新给他弹了一遍。琴师的意思是：琴曲的美妙之处就在琴曲之中，一切语言的描述都是不准确、不全面的，是多余的。软件也一样，它的原则、意图和机制都体现在软件本身之中，而不是在文档里面。

第三，从准确性的方面来说，文档往往是对软件的错误的描述。

因为文档是外在于软件的，我们无法保证文档正确地反映了软件的内在状况。软件不会骗人，它有没有实现功能需求，有没有达到吞吐量指标，是清晰而无二义的；文档则不然，一个破败不堪的软件其文档也可以写得花团锦簇。另一方面，即使文档准确地反映了当时的软件设计，随着软件的重构和进化，如果不及时更新（这是常态，因为程序员喜欢写代码而不喜欢写文档），文档也会快速变得过时。过时的文档会误导读者，过时的文档比没有文档更有害，它会引导球员把球踢进自家的球门。

软件开发不是文档开发。客户要的是可工作的软件，不是文档。开发人员是程序员，不是作家。我们绝大部分的精力应该使用在分析、设计、构建和验证软件上，需要沟通则通过简短的会议或面对面交谈，而不是通过文档的传递。尽量将需求体现在验收测试里，架构体现在模块和分包里，API体现在单元测试里。我们还需要文档，但文档的数量要尽可能的少，文档的内容要尽可能的短。文档应该只用于勾勒系统的高层概貌和设计原则，一切具体细节都应该深入到代码内部去搜寻领会。当然这样一来，就要求你的代码的可读性高，代码结构能够反映设计意图，但这不正是良好的代码应该达到的标准么？你不应该期望通过良好的文档来弥补代码的腐臭，将文档当做代码的遮羞布和除臭剂来使用。

我们要一个精美的软件，而不要一批精美的文档。如果软件是西施，粗服乱头亦不改国色；如果软件是东施，袨服华妆亦难遮其丑。可以工作的软件证明一切，完备的文档啥也证明不了。

从一位在ThoughtWorks工作的旧同事那里了解到，他们一个软件项目开发两年了，客户和产品经理在澳洲，开发人员在中国。他们通过视频会议交流，通过自动化构建和持续集成跟踪工作进度。最突出的是：这样一个大规模的、异地的、开发人员操不同母语的、业务关键的（保险业）软件，从开发至今，一份文档都没有。

二.实践思考

本人正在实践敏捷管理，如上是摘自部分敏捷实践者的观点，我并非完全赞同。在如下观点的基础上，我想补充的是，在制造业下的IT是很难做到分工及其明细的，我们的小伙伴们除了要开发产品还要运维产品。

在产品的整个生命周期内，文档或文字记录应该如何开展，做到哪个颗粒度？

1.产品从无到有：

基本在项目制的环境下诞生，故如何以最小的代价将项目做好是关键的。这个阶段我是赞同如上很多观点的。小伙伴们要输出组织要求输出的文档即可，这些都是组织经过反复讨论的，考虑到了项目过程中软件质量的问题，也考虑到了后期的运维，知识的传递。

2.产品运维阶段：

若存在运维和开发不是同一个小伙伴，请做好上一阶段知识承接。整个运维是漫长的过程，请将运维知识登记到系统。这个登记的过程，实际上是很难约定颗粒度和质量的，我个人的看法是运维分类>问题描述>解决方案：

我们要思考运维记录谁会看？目的是什么？

是给自己看嘛？痴人说梦吧，扪心自问，你登记的问题，你会再去查阅嘛？几乎不会，早在自己脑瓜里了。所以解决方案，问题描述甚至归档对你都不重要。自己记录的目的是知识输出。

是给业务运维人员看嘛？也不完全是，有多少业务运维人员能看懂开发人员登记的问题，开发写的再详细也无法解决知识缺失的问题。业务运维人员大多只能看懂问题描述和归档。故对于业务运维人员来说问题描述和归档>解决方案。业务运维看的目的是能否通过历史记录快速定位用户问题，以确定该找谁处理。

是给管理人员看嘛？占大部分吧。很多管理者无技术背景，或技术背景薄弱，再或长久不下一线，根本不知道问题如何产生的，每天就靠小伙伴汇报情况，缺乏实践。导致有时并不能看懂问题描述，更别谈解决方案了。但是有个东西叫归类，这个很重要，管理者可以通过归类来诊断组织的问题发生情况，进而倒推哪些需要关注，用管理的手段推动组织中各级小伙伴重新审视已经归档的问题描述和解决方案，来降低运维问题，提升组织效率。

总结下第2点，运维阶段登记的意义在于驱动组织更好的运维。