AICon 上海站|90%日程已就绪,解锁Al未来! 了解详情
写点什么

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

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

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

关注

评论

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

java程序员培训 | Java设计模式之桥接模式

@零度

设计模式 JAVA开发

DevEco Device Tool 助力OpenHarmony设备开发

OpenHarmony开发者

OpenHarmony

“芯”有灵“蜥”,万人在线!龙蜥社区走进 Intel MeetUp 精彩回顾

OpenAnolis小助手

开源 直播 Meetup 龙蜥社区 走进 Intel

quarkus+saas多租户动态数据源切换实现简单完美

weir威尔

SaaS 多租户 Quarkus 动态数据源

《Java编程思想》作者Bruce Eckel新作,到底做了哪些升级?

图灵教育

Java

不止于观测|阿里云可观测套件正式发布

阿里巴巴云原生

阿里云 云原生 可观测 套件

Vone新闻 | 旺链科技赋能众享链网自组织管理,打造企业级联盟DAO

旺链科技

区块链 产业区块链 DAO 自组织协作

想学习eTS开发?教你开发一款IQ-EQ测试应用

HarmonyOS开发者

HarmonyOS

并购增资或将有望启动东软越通新动能?

E科讯

navicat定时任务无效

源字节1号

Go 语言使用 MySQL 的常见故障分析和应对方法

百度Geek说

Go MySQL

坚持五件事,带你走出迷茫困境!

博文视点Broadview

运行时应用自我保护(RASP):应用安全的自我修养

SEAL安全

RASP

Kafka ETL 之后,我们将如何定义新一代实时数据集成解决方案?

tapdata

kafka ETL 数据集成 实时数据 DaaS

【云舟说直播间】-数字安全专场明天下午正式上线

云计算

开发增效利器—2022年VsCode插件分享

中原银行

ide vscode 插件 中原银行 降本增效

如何用 Redis 实现一个分布式锁

Ayue、

redis 分布式锁

使用Mycat进行MySQL单库分表

迷彩

架构 运维 mycat 分布式数据库中间件 6月月更

成熟的知识管理,应具备哪些条件?

小炮

Linux开发_摄像头编程(实现拍照、网页监控功能)

DS小龙哥

6月月更

Angular 服务器端渲染应用一个常见的内存泄漏问题

汪子熙

typescript 前端开发 angular Spartacus 6月月更

Rancher 2.6 全新 Monitoring 快速入门

Rancher

Kubernetes k8s rancher

java培训 | Java设计模式之装饰者设计模式

@零度

JAVA开发

得物多活架构设计之路由服务设计

得物技术

架构 高可用 架构设计 双活 路由

5 个关于 NFT 的技术漏洞

devpoint

区块链 以太坊 NFT 6月月更

如何使用 Django Forms 创建表单?

海拥(haiyong.site)

Python django 6月月更

大数据培训 | Flink如何监控恶意登录

@零度

大数据

大数据培训 | 电商用户行为分析之订单支付实时监控

@零度

大数据 flink

消息队列的丢失、重复与积压问题

Damon

6月月更

直播带货app源码搭建中,直播CDN的原理是什么?

开源直播系统源码

软件开发 直播带货 直播系统 app源码

攻防演练合集 | 3个阶段,4大要点,蓝队防守全流程纲要解读

青藤云安全

网络安全 网络攻防 安全服务 攻防演练

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