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

infoq

infoq

· 2014.04.05

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

播放 暂停

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

00:00 05:51

敏捷开发中的文档何时写

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

在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授权钛媒体发表,并经钛媒体编辑,转载请注明出处、作者和本文链接
本文观点仅代表作者本人,钛媒体平台仅对用户提供信息及决策参考,本文不构成投资建议。
想和千万钛媒体用户分享你的新奇观点和发现,点击这里投稿 。创业或融资寻求报道,点击这里

敬原创,有钛度,得赞赏

”支持原创,赞赏一下“
钛友趣763786 单晶冰糖啦啦啦 钛粉89798 钛粉00698 刘成军 已注销用户
526人已赞赏 >
526换成打赏总人数526人赞赏钛媒体文章
关闭弹窗

挺钛度,加点码!

  • ¥ 5
  • ¥ 10
  • ¥ 20
  • ¥ 50
  • ¥ 100

支付方式

确认支付
关闭弹窗

支付

支付金额:¥6

关闭弹窗
sussess

赞赏金额:¥ 6

赞赏时间:2020.02.11 17:32

关闭弹窗 关闭弹窗

Oh! no

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

注册邮箱未验证

我们已向下方邮箱发送了验证邮件,请查收并按提示验证您的邮箱。

如果您没有收到邮件,请留意垃圾邮件箱。

更换邮箱

您当前使用的邮箱可能无法接收验证邮件,建议您更换邮箱

账号合并

经检测,你是“钛媒体”和“商业价值”的注册用户。现在,我们对两个产品因进行整合,需要您选择一个账号用来登录。无论您选择哪个账号,两个账号的原有信息都会合并在一起。对于给您造成的不便,我们深感歉意。