【开发】敏捷中的文档:写多少、何时写?

摘要: 敏捷开发宣言强调“可以工作的软件胜过面面俱到的文档”。该核心价值要求我们去及思考要编写多少文档,需要编写什么类型的文档以及什么时候需要去编写文档。

敏捷开发中的文档何时写

敏捷开发宣言强调“可以工作的软件胜过面面俱到的文档”。该核心价值要求我们去及思考要编写多少文档,需要编写什么类型的文档以及什么时候需要去编写文档。

在Jonathan Berger的博文《最低限度交付物》一文中,提到关于在设计阶段的决策沟通。他对有关编写文档 的观点如下:

敏捷宣言更喜欢“可以工作的软件胜过面面俱到的文档”,那么,为什么设计者还要花时间在用户将永不会看到的东西上?敏捷的目的是尽量减少浪费,所以采取了极端的逻辑,所有的文档都是浪费的东西。这并不意味着文档可以(或应该)被完全抛弃掉。文档对于团队来说是有用的(特别是当团队要扩展规模时)。但宣言建议,减少文档是一件好事,而设计者应该寻求利用最少量的文档沟通设计决策。

Jonathan针对如何尽量减少文档提供了如下建议:

1) 在你的团队中普及“越少的东西会更好”的理念。

2)时刻思考这个问题:我们马上需要交付的最少量的交付物有哪些?

Ashish Sharma在《敏捷的本质、价值和及时的文档》一文中,提到如何在文档和讨论之间取得平衡:

敏捷的目标应该是在文档和讨论之间的适当平衡。文档是每个系统的重要组成部分。无论是否采用敏捷或其他方法,相当全面的文档并不能保证项目的成功。事实上,它会增加失败的机会。

他提到当考虑要写多少文档和什么时候去编写的时候,可以参考下面三个标准:

必不可少:文档应该仅够用但详细。

有价值的:编写文的确所需要的文档,而不是我们想编写时才编写的文档。

及时:文档应该当我们需要的时候,以及时的方式(JIT)编写。

Michael Nygard 描述了对文档相关流程的看法。他建议用一开始就考虑结果的方式去思考流程:

我经常发现很多流程都没有消费者。这纯粹就是浪费!从表面上看没人使用输出物,但过程的负责人根本没意识到。

Michael建议,流程包括它们的输入和输出都能从消费者的角度去描述。他分享了可以下面的问题去协助描述:

谁是最终消费者?

他们的需求是什么?

你如何交付给他们?

你如何知道他们如何准备好?

你如何生产?

你需要什么输入去生产产品?

Tom de Lancey于2013年早些时候在 LinkedIn中开展的关于《紧急的文档:敏捷与瀑布模型的一个重要区别》中说道:

很多人对于放弃他们熟悉经常使用的文档感到不舒服:系统需求、系统设计、愿景和范围、用例、模式、工作流程图、Rational统一过程文档等。很多人都不能将这些文档分拆成五个句子的故事。

他描述了一种称为“紧急文档”的分析方法用于编写文档:

(…)我们不会浪费时间和精力在编写那些我们未曾发现如何去做的文档上。当我们发现问题的时候才编写文档。我们编写实际所需要的文档,而不是那些我们想去写的文档。

TOM说的紧急文档的其中一个好处是:

文档变成开发过程的一个部分,而不是单独的活动。因为文档实际上是十分有用的,整个团队都有兴趣去维护它。每一个用户故事都有单独的任务需要去更新WIKI(使用一个将每个用户故事相互连接的SharePoint网站)。

Mario Moreira写了一篇关于《敏捷世界的正常文档规模》的博文。正如Mario说的,适当调整规模是对过去或现在有大量的文档的软件项目的响应:

文档的正常规模意味着,编写和维护文档的精力投入加上所写文档自身的价值,相比没有该文档(比如,重新组织信息的投入和没有文档对当前决策带来的影响),应该能获得更好地投资回报率,

他的博文提供了在正常文档规模的建议。他的部分建议如下:

文档应当采取合作的性质。它不应只由一人编写得那么完美,而应该与他人分享。应当在草稿阶段就进行分享以获得足够的信息。

关注仅仅够好的文档并且避免太多的前期细节,因为那样意味着很多的猜测并且会浪费时间。仅仅够好意味着只针对当前所了解的编写文档。

文档应该以多种形式存在。不但只是Word格式的文档,还可以存在于wiki、存在于敏捷工具,或代码中的注释或其他。

各位是如何编写文档的?要编写多少和何时开始呢?欢迎讨论。

查看英文原文:Documentation in Agile: How Much and When to Write It?

技术控是百度新闻与钛媒体合作,专门为技术爱好者打造的栏目

本文系作者 infoq 授权钛媒体发表,并经钛媒体编辑,转载请注明出处、作者和本文链接
分享到:

第一时间获取TMT行业新鲜资讯和深度商业分析,请在微信公众账号中搜索「钛媒体」或者「taimeiti」,或用手机扫描左方二维码,即可获得钛媒体每日精华内容推送和最优搜索体验,并参与编辑活动。

infoq
infoq

InfoQ是一家国际性的公司,在加拿大、美国、中国和罗马尼亚均设有办公室。目前,我们运作两大品牌产品:InfoQ网站,以及QCon大会。InfoQ目前设有英文站、中文站、日文站和巴西葡文站。

评论(1

  • 广告人问答社区 广告人问答社区 2014-04-08 08:46 via weibo

    沟通的形式工具内容 一直在变化!

    0
    0
    回复

Oh! no

您是否确认要删除该条评论吗?

分享到微信朋友圈