如何写一份敏捷的文档

一、什么是“文档”

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

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

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

二、敏捷文档≠不写文档

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

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

在这里我们就假设在软件开发过程中是可以不写任何文档的，那我们日常的工作场景可能会是这样的：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1、WHO-谁需要文档？
我们在做产品规划时，都会先做个用户画像，以确定我们的产品服务于哪些客户，用户画像可以帮助团队从“以功能为中心”转向“以用户为中心”做产品设计。

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

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

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

• 首先，你提供的文档要抓住客户的痛点，否则客户肯定会不断的要求你提供更多的文档。
• 其次，要客户非常具体地描述他对文档的需求，一定不能接受泛泛而谈的需求。比如客户说“我要一份产品文档”，这个“产品文档”就太泛了，但是如果说“我要一份产品的原型图”就具体多了。
• 第三，要确定文档的载体，也就是具体形式，比如是word，是Axure源文件，还是HTML？
• 最后，告诉客户你制作文档所需的工作量，你在文档上投入的任何时间，你本都可以用在新功能的开发上的，你必须让客户意识到这点，这样客户才不至于无止境的提文档的要求。

一个推荐的做法是，把文档也当做是需求，排入到Backlog中，通过将文档视为需求，你可以将其工作量提供给利益相关方（可能不止文档的使用者）做参考，以此决定文档要不要写、写到什么程度。从根本上说，对文档的投资是一个商业决策，而不是技术决策： 文档不应该为流程或规章制度而创建，文档应该为你的利益相关者而创建。

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

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个要素的。

4、HOW-怎样提供？
上一节我们聊到，我们提供文档的目的是 为了沟通和理解，为了更好的达到这个目标，我们要怎么做呢？丛斌老师在他的《知行合一：实现价值驱动的敏捷和精益开发》一书中给了一个沟通热度及其有效性的模型，如下图所示：

从上图可以看出，“有问题澄清环节”的沟通方式（邮件、电话、白板讨论等）在沟通热度和有效性方面都明显高于“无问题澄清环节”（录音、录像、纯文字等）的沟通方式，所以我们应该优先选择“有问题澄清环节”的沟通方式，同时在沟通完成以后，按照客户的需要，及时整理出适量的文档（比如电话的录音、白板的照片等）。但是是不是“无问题澄清环节”的沟通方式就一无是处了呢？也不一定，在某些情况下，比如交流个体之间的距离（无论是物理上的还是时间上的）很大时，“无问题澄清环节”的沟通方式会是一个更好的选择，这种沟通方式，就需要准备大量的文字、语音或视频文档了。

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

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

这个实践的一种极端方式是等到你系统上线后再写文档，这种方式的主要的优点是你写的都是已知的、稳定的内容（你已经发布的软件）。不过这种做法有几个明显的缺点：

• 这时你很可能已经忘记了某些决定背后的原因，如果这些原因对你很重要的话，这个问题会很严重；
• 你可能没有合适的人再去写文档了，因为他们可能已经转向其他项目了；
• 你可能没有预算来做这项工作；
• 编写文档的意愿可能不复存在。

所以我们应该尽可能的推迟敏捷文档的提供时间，但是不要一直推迟到项目结束了才写，同时我们要在项目过程中时刻记录有用的素材。

6、WHERE-从哪里开始？
前面说了这么多，很多人可能还是有一个疑惑，敏捷文档到底应该要从哪开始写？虽然我在前面画了这么一张图：

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

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

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

五、小结

如果敏捷文档要用一句话来总结的话，那就是： 在正确的时间，找到正确的人，发掘正确的需求，使用正确的方法，完成正确的文档！