【AICon】探索RAG 技术在实际应用中遇到的挑战及应对策略!AICon精华内容已上线73%>>> 了解详情
写点什么

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

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

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

关注

评论

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

IP地址分类及范围

郑州埃文科技

IP地址 IP地址分类 IP地址范围

深入理解完美哈希

C++后台开发

hash 后端开发 C++后台开发 哈希函数 C++开发

运行时,物体移动旋转缩放插件,“RuntimeTransformGizmos插件”使用教程(Unity3D)

恬静的小魔龙

游戏开发 Unity 插件 虚拟仿真 游戏引擎

同构+跨端,懂得小程序+kbone+小程序容器就够了!

Geek_99967b

小程序容器

hive数据导入:Python脚本

怀瑾握瑜的嘉与嘉

Python hive 7月月更

饿了么为啥给你推荐这个?本地生活搜索算法解密

阿里技术

算法 性能提升

2022年中国人工智能产业生态图谱

易观分析

人工智能

Idea 连接 MySQL 数据库

攻城狮杰森

MySQL IDEA database 7月月更

浅谈负载

Damon

7月月更

K8S多集群管理很难?试试Karmada | K8S Internals系列第3期

BoCloud博云

容器 容器云 K8s 多集群管理

同城订单同城送,爆单依旧得心应手!

CRMEB

想要制作沙盒游戏?那么这一款插件你一定不能错过(Unity3D)

恬静的小魔龙

Unity

EMQ映云科技荣登《中国企业家》2022年度“新锐100”榜单

EMQ映云科技

开源 物联网 IoT emq 7月月更

这次和GrowingIO工程师一起搞事情 | StartDT Hackathon

奇点云

数字化转型失败的罪魁祸首是什么?

雨果

数字化转型 DaaS数据即服务

移动研发平台EMAS 3.0全新升级,欢迎登陆阿里云官网搜索EMAS进行体验

移动研发平台EMAS

阿里云 emas 移动测试 移动研发 产品架构

用Unity做仿真,这款图表插件我不允许你不知道

恬静的小魔龙

Unity

还在被电影中吧爆炸的画面震撼?那你一定不要错过这款Unity的爆炸插件

恬静的小魔龙

Unity

Spirng之Annotation注解与AOP使用

echoes

2022长三角工业自动化展会将于10月在南京国际展览中心召开

AIOTE智博会

工业自动化展会 工业机器人展会 江苏工博会

Kyligence 出席华为全球智慧金融峰会,加速拓展全球市场

Kyligence

数据湖 数据分析 OLAP

融云超级群的「新能力」

融云 RongCloud

ios Android;

void 0 有什么意义?undefined竟然是可变的?

南极一块修炼千年的大冰块

7月月更

还在用Unity开发游戏?那你就out了,试试用Unity做一个答题系统吧

恬静的小魔龙

Unity

Python 爬虫 JS 逆向 X-Bogus,signature 加密算法,AST 理论篇

梦想橡皮擦

Python 爬虫 7月月更

数字藏品系统开发——商城盲盒h5平台搭建

开源直播系统源码

数字藏品 数字藏品系统软件开发 NFT数字藏品系统 数字藏品源码出售 数字藏品交易平台开发

2022年中国第三方支付市场专题分析

易观分析

第三方支付

带你认识8个软件设计中的谬误

华为云开发者联盟

后端 分层架构 开发

国产统信UOS系统运行小程序的探索

Geek_99967b

小程序

膜拜~ 终于拿到了美团老大哥分享的 Netty 源码剖析与应用 PDF

程序知音

Java 程序员 架构 Netty 后端技术

终于有人把操作系统、网络系统、线程进程、IO模型全部总结出来了

程序知音

Java 后端 操作系统 网络 TCP/IP

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