报名参加CloudWeGo黑客松,奖金直推双丰收! 了解详情
写点什么

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

  • 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:362483
用户头像

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

关注

评论

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

gRPC快速整合SpringCloud

Java你猿哥

Java gRPC Spring Cloud 后端 ssm

大数据计算引擎 EasyMR:拥抱开源,引领技术创新

袋鼠云数栈

大数据 大数据基础平台

模型训练过程中,混合精度训练稳定性解决方案

Openlab_cosmoplat

模型训练 开源社区

电力行业等保定级评级依据是什么?分为几个等级?

行云管家

电力 等保 等保测评

聊聊池化层和步长为2的卷积层

华为云开发者联盟

人工智能 华为云 华为云开发者联盟 企业号 3 月 PK 榜 卷积层

赋能数字经济新动能 焱融科技获评「人工智能高质量发展-行业责任担当」企业

焱融科技

人工智能 文件存储 容器存储 分布式文件存储 全闪存储

【活动报名】 拥抱公平《 Impact Tech, She Can 》

亚马逊云科技 (Amazon Web Services)

人工智能

开门见山|首期《崖山论“见”》技术 Meetup启程

YashanDB

2023年实用性好的堡垒机推荐

行云管家

网络安全 堡垒机

矩阵佛萨奇(MetaForce)合约开发源码搭建

薇電13242772558

web3

优秀!阿里甩出GC面试小册,仅7天Github获赞96.9K

Java你猿哥

Java ssm 面经 GC Java工程师

JAVA实战:如何让单元测试覆盖率达到80%甚至以上

Java你猿哥

Java ssm 单元测试 Java工程师 java实战

直击面试!阿里技术官手码12W字面试小册在Github上爆火

Java你猿哥

Java 后端 面经 简历 Java工程师

ITSM | 如何通过设计提升工单处理效率

嘉为蓝鲸

IT ITSM 流程管理

蛇形走线用在哪里,一文告诉你

华秋PCB

信号 PCB PCB设计 布线 滤波

软件测试/测试开发丨app自动化测试之Appium 源码修改定制分析

测试人

软件测试 自动化测试 测试开发 appium

精华抢先看|龙蜥社区操作系统安全两大白皮书即将重磅发布

OpenAnolis小助手

操作系统 白皮书 系统安全 Meetup 龙蜥社区

小程序营销模板的发展现状及前景分析

没有用户名丶

小程序

BugBuilder: 高质量大规模缺陷库自动构建方法

华为云开发者联盟

开发 华为云 补丁 华为云开发者联盟 企业号 3 月 PK 榜

2023飞书未来无限大会谢欣演讲highlight:三件套、Office提升、出海

B Impact

瓴羊Quick BI数据门户,让管理企业像浏览网页一样轻松

对不起该用户已成仙‖

在 Kubernetes 中部署应用交付服务(第 1 部分)

NGINX开源社区

ChatGPT能否取代程序员?仍然是一个需要认真探讨的问题,对此你怎么看?

兴科Sinco

OpenAPI openai #人工智能 ChatGPT

手把手教你如何使用MyBatisPlus

Java你猿哥

mybatis 实战 Mybatis-Plus

记一次 rr 和硬件断点解决内存踩踏问题

NebulaGraph

数据库 debug

XLD音频无损解码器:X Lossless Decoder中文激活版

真大的脸盆

Mac Mac 软件 音频解码 音频处理工具 音频管理

MySQL中这14个小玩意,让人眼前一亮!

Java你猿哥

Java MySQL 后端 ssm Java工程师

2023年好用的谷歌浏览器插件推荐(Chrome必备扩展程序) 安装教程

互联网搬砖工作者

开发和测试融合,到底该怎么做?

BY林子

敏捷开发 敏捷测试

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