写点什么

敏捷中的文档: 写多少、何时写?

  • 2014-03-31
  • 本文字数:1692 字

    阅读完需:约 6 分钟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. 谁是最终消费者?
  2. 他们的需求是什么?
  3. 你如何交付给他们?
  4. 你如何知道他们如何准备好?
  5. 你如何生产?
  6. 你需要什么输入去生产产品?

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 中文站投稿或者参与内容翻译工作,请邮件至 editors@cn.infoq.com 。也欢迎大家通过新浪微博( @InfoQ )或者腾讯微博( @InfoQ )关注我们,并与我们的编辑和其他读者朋友交流。

2014-03-31 07:362666
用户头像

发布了 81 篇内容, 共 27.2 次阅读, 收获喜欢 5 次。

关注

评论

发布
暂无评论
发现更多内容

如何判断两个字符串是否互为回文?

InfoQ IT百科

消息传递通信的实现方式?

InfoQ IT百科

输入一个链表,输出该链表中倒数第k个结点。

InfoQ IT百科

什么是完全二叉树?

InfoQ IT百科

大咖说 X 对话开源|论数据库人才发展战略

大咖说

数据库 阿里云 科技

算法的五大特征是什么?

InfoQ IT百科

Plato Farm 的MARK 处于永远通缩,经济模型解析

西柚子

单调栈与栈的区别是什么?

InfoQ IT百科

什么是“哈希算法”?

InfoQ IT百科

有一个已经排好序的数组。现输入一个数,要求按原来的规律将它插入数组中。

InfoQ IT百科

数组去重的5种方法是什么?

InfoQ IT百科

计算单链表的长度。

InfoQ IT百科

netty系列之:netty中常用的对象编码解码器

程序那些事

Java Netty 程序那些事 4月月更

玩转小程序压测

阿里巴巴云原生

小程序 阿里云 云原生 压测 PTS

EventBridge 集成云服务实践

阿里巴巴云原生

阿里云 云原生 事件总线 EventBridge 事件源

加密算法有哪几种?

InfoQ IT百科

易周金融观点 | 个人养老金制度正式出炉;居民贷款延期还款政策密集落地

易观分析

银行 养老金制度

进程主要由哪几个部分组成?

InfoQ IT百科

什么是分治算法?

InfoQ IT百科

计算机操作系统最基本的特征是什么?

InfoQ IT百科

阿里云数字化安全生产平台 DPS V1.0 正式发布!

阿里巴巴云原生

阿里云 云原生 数字化 安全生产平台

动态重定位需要由什么来实现?

InfoQ IT百科

CPU散热器是电脑标配吗?

InfoQ IT百科

什么是满二叉树?

InfoQ IT百科

数据结构和算法的关系?

InfoQ IT百科

在Windows中,当一个应用程序窗口被关闭,该应用程序将会保留在哪里?

InfoQ IT百科

递归算法的三个定律是什么?

InfoQ IT百科

国厂自研的操作系统都有哪些?

InfoQ IT百科

给定两个字符串s和t,判断这两个字符串中的字母是不是完全一样。

InfoQ IT百科

企业如何进行数字化转型?零代码简道云剑指「全民开发」新机遇

ToB行业头条

图数据库|如何从零到一构建一个企业股权图谱系统

NebulaGraph

数据库 知识图谱

敏捷中的文档:写多少、何时写?_语言 & 开发_Ben Linders_InfoQ精选文章