如何写一份敏捷的文档

2021-04-06 15:29:09
小船哥说敏捷
转贴:
微信公众号
58


一、什么是“文档”


在分析敏捷开发中的文档之前,我们要先搞清楚什么是“文档”。


维基百科给出的解释是:具有三个基本属性,即: 知识性记录性物质性,它具有存储知识、传递和交流信息的功能。

从这个定义我们可以知道:“文档”可以理解为一切可以存贮知识、促进沟通、传递信息的有形或无形的资料。弄清楚“文档”的概念后,我们就可以继续分析敏捷开发中的文档了。


二、敏捷文档≠不写文档


很多团队在看到敏捷宣言的这句话以后: 工作的软件高于详细的文档

都会产生一个问题:既然软件比文档重要,那敏捷开发是不是可以不写文档了?


在这里我们就假设在软件开发过程中是可以不写任何文档的,那我们日常的工作场景可能会是这样的:
  • 迭代计划会的时候,没有任何书面的Backlog,PO把需求跟大家口述一遍,然后就直接开始开发;
  • 迭代的过程中,没有设计图,没有接口文档,没有测试用例,没有bug记录……;
  • 每日站会的时候没有看板,每个人都在口述自己昨天做了啥、今天要做啥,但是没人能清楚地知道总共要做多少功能,做了多少功能,还剩多少功能;
  • 需求的改动全靠口头通知,请假或未出席会议的人全凭猜;
  • PO对故事进行验收的时候,因为没有可视化的文档,导致开发团队做的东西根本不是他想要的,不停地返工;
  • 评审会上,因为bug太多,新功能演示频频翻车,客户不欢而散;
  • 回顾会上,SM发现没有任何客观数据可供回顾的,于是大家随便聊点不疼不痒的话题,散会;
  • 项目勉强上线,没有用户手册,没有运维文档,无人会使用,没人能维护;
  • 项目卒。

看完上面的描述,有些场景是不是似成相识?大家是不是觉得有些文档还是很有必要的?写很多详细的文档不合适,但是完全不写文档更不合适!


文档不仅可以让我们开发过程中的沟通更顺畅、进度更透明、变更可追踪、bug有记录,还可以让我们交付的产品更便于维护、使用和修改,可以有效延长产品的寿命。可以毫不夸张的说,文档就是产品的一部分!那既然文档如此重要,我们在敏捷开发中要写多少文档呢?


三、敏捷文档=创造价值的文档


之前我一直纠结于敏捷开发到底要写多少文档的问题,后来我在第N次阅读《Scrum指南》的时候,看到了Scrum的定义:


Scrum 是一个轻量的框架,它通过提供针对复杂问题的自适应解决方案来帮助人们、团队和组织创造价值。——《Scrum Guide 2020》


最新版的Scrum指南将Scrum的目的从“ 最高价值的产品”改成了“ 创造价值”,从上一节的描述我们知道,文档是敏捷开发的一部分,那我们在敏捷开发中写的文档有没有在“ 创造价值”呢?


我们通过文档所收获的价值,可能跟图1类似: 理想情况下,在没有任何文档的时候,写得越多(支出),收获就越多(收入),我们所获得的价值(利润)也越高(利润=收入-支出)。但是超过某个 价值最高点,我们再写更多的文档(追加投资),可能就不再产生明显的收益了(追加投资产生的收入<追加的投资),也就是我们撰写的新文档已经不能“ 创造价值”了,这时我们获得的价值总额开始下降。此时再继续写下去的话,最终会达到 收支平衡点,这时我们所交付的全部文档,已经不产生任何价值了,即我们通过写文档所获得的收入,已经跟我们的支出一样多了。

如果一份文档已经处于价值最高点了(或者已经越过价值最高点了),再写更多的文档就不能再“创造价值”了,这显然是一种浪费,一份文档一旦已经实现了它的预期目标,再对它做再多的投资只会是画蛇添足。


我们用产品文档来举个例子:我们在规划一个新产品时,一份产品愿景文档是非常有必要的,因为它可以清晰的指明产品的定位及未来的发展方向;如果我们再根据这份产品愿景文档,整理出一份用户故事地图,这也是十分有用的,因为它对于用户的画像、功能模块的划分、功能迭代的规划等都是很有帮助的。但是如果我们再进一步,根据用户故事地图写了一份详细的产品设计文档,文档包括了所有已知需求的详细描述、页面的原型设计、跳转逻辑、版本的发布日期及对应的功能列表等,这些工作就有点画蛇添足了,因为我们现在只有一个待验证的产品愿景,我们还不能确定产品的方向是否正确、用户画像是否准确、需求是否能满足最终客户的需要等,我们这时候做的这么一份详细的设计文档,很可能是用不上的。即使我们强行使用这份文档,后期的维护成本也会非常高,这份文档就属于不能“创造价值”的文档,它会导致我们交付文档的总价值降低。如果我们在做完这份详细的产品设计文档以后,再联系一家出版社,将它编辑后印刷出来,这时候我们通过这一系列的产品文档所收获的总价值(实际收益-投入成本),可能几乎就是0了!


当然上面这张图我画的有点理想化了, 写文档就像探索客户的需求一样,在达到最高价值之前,我们可能会走很多弯路,写很多不必要的文档,不过为了便于说明,我假设从一开始我们就在写那些能“创造价值”的文档。

那我们怎样才能保证自己少走弯路,确保一直在写创造价值的文档呢?


四、怎样写出一份创造价值的敏捷文档


一份文档是否可以为产品创造价值,可以通过以下 5W1H的方式来判断:

3.1.WHO-谁需要文档?

我们在做产品规划时,都会先做个用户画像,以确定我们的产品服务于哪些客户,用户画像可以帮助团队从“以功能为中心”转向“以用户为中心”做产品设计。


我们写文档的时候也是一样,在决定要写一份文档之前,我们要首先考虑到文档的使用者是谁?是客户、是用户、是产品人员、是开发人员还是公司领导?角色不同,对文档的需求可能也会不同,所以我们只有首先确定了文档的使用者,才有可能写出满足客户需要的、创造价值的文档。


这里有个概念大家需要注意一下: 我们要确认的是文档的“使用者”,而不是“提出者”。这两者有什么区别呢?相信大家都听过一句话:“你妈觉得你冷”,文档的提出者就可以类比为妈妈,而文档的使用者可以类比为孩子——孩子冷不冷,只有孩子自己才知道。

3.2.WHAT-需要什么文档?

当有人跟你提出需要文档时,一定是因为他的某些需求没有得到满足,那我们需要提供什么样的文档才能满足客户的需求呢?这里记住4个原则。

  • 首先,你提供的文档要抓住客户的痛点,否则客户肯定会不断的要求你提供更多的文档。
  • 其次,要客户非常具体地描述他对文档的需求,一定不能接受泛泛而谈的需求。比如客户说“我要一份产品文档”,这个“产品文档”就太泛了,但是如果说“我要一份产品的原型图”就具体多了。
  • 第三,要确定文档的载体,也就是具体形式,比如是word,是Axure源文件,还是HTML?
  • 最后,告诉客户你制作文档所需的工作量,你在文档上投入的任何时间,你本都可以用在新功能的开发上的,你必须让客户意识到这点,这样客户才不至于无止境的提文档的要求。
一个推荐的做法是,把文档也当做是需求,排入到Backlog中,通过将文档视为需求,你可以将其工作量提供给利益相关方(可能不止文档的使用者)做参考,以此决定文档要不要写、写到什么程度。从根本上说,对文档的投资是一个商业决策,而不是技术决策: 文档不应该为流程或规章制度而创建,文档应该为你的利益相关者而创建


PS. 如果你所在的组织确实在为流程而写文档,这时可以打开《Scrum指南》,翻到“Scrum Master 以多种方式服务于组织”一节,告诉Scrum Master,这正是他发挥作用的时刻!但是要注意一点,《Scrum指南》中只说了Scrum Master要服务于自己的组织,如果另一个组织对你所在的组织有不合理的要求,比如你作为乙方在为甲方做一个项目,甲方强制要求你在每个里程碑节点的时候都要提供一堆文档,这一点就超出Scrum Master的控制范围了。

3.3.WHY-为什么需要?

为什么要写这个文档?撰写文档肯定是为了有所回报(创造价值):可能是为了推销产品(用户手册、售后指南等),也有可能是为了降低沟通成本(产品原型文档、接口文档等),也有可能纯粹是为了通过某个流程(比如你作为乙方为了通过甲方的验收)。但不管怎么样,在写任何类型的文档前都要先搞清楚其背后的原因:客户现在是如何做的、为什么需要新的文档、他们希望如何使用新的文档、有了新的文档以后会有哪些收益等等。


这里需要注意一点,不管客户的真实需要是什么,大多数情况下,我们写文档的目的都是为了沟通,而沟通的主要目的是理解!知道了这个逻辑以后,我们可能就不会再醉心于完善的、精美的文档了,因为 文档只是一个工具,沟通和理解才是目的


看完了前面3条:“Who-What-Why”,你有没有觉得这个结构有点熟悉?没错,就是用户故事的3要素:As a 【role(Who)】, I want 【function(What)】, so that 【business value(Why)】。


用户故事通过这3个要素,就能保证做出来的功能是有价值的,那我们要写的文档是不是也可以只通过这3个要素来判断有没有价值呢?


用户故事只要3个要素就能把一个事情说的明白,是因为用户故事有几个隐含的条件:软件的解决方案是Scrum团队和利益相关方在Sprint计划会上集体讨论出来的(How),使用者是通过APP或web使用软件的(Where),软件中发生的事情都是在使用期间或预期时间(比如闹钟)发生的(When)。但是敏捷开发中的文档,是没有这些隐含条件的,所以我们还是需要继续探索5W1H中剩下的3个要素的。

3.4.HOW-怎样提供?

上一节我们聊到,我们提供文档的目的是 为了沟通和理解,为了更好的达到这个目标,我们要怎么做呢?丛斌老师在他的《知行合一:实现价值驱动的敏捷和精益开发》一书中给了一个沟通热度及其有效性的模型,如下图所示:
从上图可以看出,“有问题澄清环节”的沟通方式(邮件、电话、白板讨论等)在沟通热度和有效性方面都明显高于“无问题澄清环节”(录音、录像、纯文字等)的沟通方式,所以我们应该优先选择“有问题澄清环节”的沟通方式,同时在沟通完成以后,按照客户的需要,及时整理出适量的文档(比如电话的录音、白板的照片等)。但是是不是“无问题澄清环节”的沟通方式就一无是处了呢?也不一定,在某些情况下,比如交流个体之间的距离(无论是物理上的还是时间上的)很大时,“无问题澄清环节”的沟通方式会是一个更好的选择,这种沟通方式,就需要准备大量的文字、语音或视频文档了。

3.5.WHEN-何时提供?

敏捷开发中需求管理经常采用的策略是推迟决策,创建敏捷文档的时间也遵循这个策略,我们要尽可能的推迟所有文档的创建时间,如下图所示,只有在我们实际需要的时候再去创建它们。例如,系统概要文档最好是在一个版本的开发末期编写,因为只有在这时你才知道你实际构建了什么。同样,大部分的运营支持文档也最好在项目生命周期的最后来写。但是,这并不意味着所有的文档都应该留到最后。团队应该在整个开发过程中为最后要交付的文档记录素材,这样你就不会丢失关键信息。开发过程中记录的素材最好只是一些零散的信息,因为在最终交付之前,没必要对文档进行仔细打磨。

在项目信息稳定后再撰写文档,你可以有效降低与文档相关的成本和风险:成本降低是因为你不会浪费时间去修改文档中已经变化的信息;风险降低是因为你现有文档过时的可能性大大降低。如果你提前写完了文档,但是文档中包含的信息都还只是个规划,那么一旦信息发生变化,你就会面临修改文档甚至是重新编写文档的风险。换句话说, 你不应该在项目早期投入大量时间来记录计划的想法,比如需求、设计等。相反,我们最好等到项目的后期,等系统已经初具雏形,并确定好哪些信息对你真正有用的时候再去撰写文档。


这个实践的一种极端方式是等到你系统上线后再写文档,这种方式的主要的优点是你写的都是已知的、稳定的内容(你已经发布的软件)。不过这种做法有几个明显的缺点:
  • 这时你很可能已经忘记了某些决定背后的原因,如果这些原因对你很重要的话,这个问题会很严重;
  • 你可能没有合适的人再去写文档了,因为他们可能已经转向其他项目了;
  • 你可能没有预算来做这项工作;
  • 编写文档的意愿可能不复存在。
所以我们 应该尽可能的推迟敏捷文档的提供时间,但是不要一直推迟到项目结束了才写,同时我们要在项目过程中时刻记录有用的素材

3.6.WHERE-从哪里开始?

前面说了这么多,很多人可能还是有一个疑惑,敏捷文档到底应该要从哪开始写?虽然我在前面画了这么一张图:

但是这只是一个示例,我并不是建议大家都按照“ 敏捷开发方式”的示意来写。因为每个公司的项目类型、管理方式、规章制度可能都不一样,所以这一点是没法给出一个标准的实践方法的,我的建议是 从现状开始!可能有人看到这个答案就笑了:我们现在就是在写一堆无用的文档,你让我从现状开始?


这里我要解释下我所说的“现状”的含义: 现状不是指你们现在在写哪些文档,而是你们现在在使用哪些文档。比如你们在日常的开发过程中一直在用设计图、接口文档等,并在整个项目过程中保持更新,那么这是一个很好的迹象,说明这些资料都是很有价值的项目信息,你应该围绕着这些信息来编写文档。对于那些没有保持更新或更新以后也基本无人问津的文档,这些文档很可能就是在为了流程而写,再持续编写这类文档就没有任何价值了。


所以从现状开始的含义是: 你可以从团队一直在使用的项目信息开始写文档,然后在敏捷迭代的过程中,也持续不断的迭代你的文档


五、小结


如果敏捷文档要用一句话来总结的话,那就是: 在正确的时间,找到正确的人,发掘正确的需求,使用正确的方法,完成正确的文档
文章分类
联系我们
  • 联系人:郑女士
  • 联系方式: 13792883250
  • 地址:青岛开发区长江中路232号国贸中心C座
投稿邀请

如果您有优秀的原创文章,欢迎添加联系人直接与我们联系,或通过下方邮箱发送投稿文章,一经采用,我们会付以一定的稿件报酬。

  • 投稿邮箱: [email protected]
  • 投稿标题:向 [敏捷开发] 网站投稿
  • 稿件要求:与敏捷开发相关的任何内容

更多投稿相关请点击更多进行了解~