共计 5676 个字符，预计需要花费 15 分钟才能阅读完成。
一、什么是“文档”
在剖析麻利开发中的文档之前，咱们要先搞清楚什么是“文档”。
维基百科给出的解释是：
具备三个根本属性，即：知识性、记录性、物质性，它具备存贮常识、传递和交流信息的性能。
从这个定义咱们能够晓得：“文档”能够了解为所有能够存贮常识、促成沟通、传递信息的无形或有形的材料。
弄清楚“文档”的概念后，咱们就能够持续剖析麻利开发中的文档了。
二、麻利文档≠不写文档
很多团队在看到麻利宣言的这句话当前：
工作的软件高于具体的文档
都会产生一个问题：既然软件比文档重要，那麻利开发是不是能够不写文档了？
在这里咱们就假如在软件开发过程中是能够不写任何文档的，那咱们日常的工作场景可能会是这样的：
- 迭代打算会的时候，没有任何书面的 Backlog，PO 把需要跟大家口述一遍，而后就间接开始开发；
- 迭代的过程中，没有设计图，没有接口文档，没有测试用例，没有 bug 记录……；
- 每日站会的时候没有看板，每个人都在口述本人昨天做了啥、明天要做啥，然而没人能分明地晓得总共要做多少性能，做了多少性能，还剩多少性能；
- 需要的改变全靠口头告诉，销假或未出席会议的人全凭猜；
- PO 对故事进行验收的时候，因为没有可视化的文档，导致开发团队做的货色基本不是他想要的，不停地返工；
- 评审会上，因为 bug 太多，新性能演示频频翻车，客户不欢而散；
- 回顾会上，SM 发现没有任何主观数据可供回顾的，于是大家轻易聊点不疼不痒的话题，散会；
- 我的项目勉强上线，没有用户手册，没有运维文档，无人会应用，没人能保护；
- 我的项目卒。
看完下面的形容，有些场景是不是似成相识？大家是不是感觉有些文档还是很有必要的？
写很多具体的文档不适合，然而齐全不写文档更不适合！
文档不仅能够让咱们开发过程中的沟通更顺畅、进度更通明、变更可追踪、bug 有记录，
还能够让咱们交付的产品更便于保护、应用和批改，能够无效缩短产品的寿命。能够毫不夸大的说，文档就是产品的一部分！
那既然文档如此重要，咱们在麻利开发中要写多少文档呢？
三、麻利文档=发明价值的文档
之前我始终纠结于麻利开发到底要写多少文档的问题，起初我在第 N 次浏览《Scrum 指南》的时候，看到了 Scrum 的定义：
Scrum 是一个轻量的框架，它通过提供针对简单问题的自适应解决方案来帮忙人们、团队和组织发明价值。——《Scrum Guide 2020》
最新版的 Scrum 指南将 Scrum 的目标从“最高价值的产品”改成了“发明价值”，从上一节的形容咱们晓得，文档是麻利开发的一部分，那咱们在麻利开发中写的文档有没有在“发明价值”呢？
咱们通过文档所播种的价值，可能跟图 1 相似：现实状况下，在没有任何文档的时候，写得越多（收入），播种就越多（支出），咱们所取得的价值（利润）也越高（利润 = 支出 - 收入）。
然而超过某个价值最高点，咱们再写更多的文档（追加投资），可能就不再产生显著的收益了（追加投资产生的支出 < 追加的投资），也就是咱们撰写的新文档曾经不能“发明价值”了，这时咱们取得的价值总额开始降落。此时再持续写下去的话，最终会达到收支平衡点，这时咱们所交付的全副文档，曾经不产生任何价值了，即咱们通过写文档所取得的支出，曾经跟咱们的收入一样多了。
如果一份文档曾经处于价值最高点了（或者曾经越过价值最高点了），再写更多的文档就不能再“发明价值”了，这显然是一种节约，一份文档一旦曾经实现了它的预期指标，再对它做再多的投资只会是画龙点睛。
咱们用产品文档来举个例子：咱们在布局一个新产品时，一份产品愿景文档是十分有必要的，因为它能够清晰的指明产品的定位及将来的倒退方向；如果咱们再依据这份产品愿景文档，整顿出一份用户故事地图，这也是非常有用的，因为它对于用户的画像、功能模块的划分、性能迭代的布局等都是很有帮忙的。然而如果咱们再进一步，依据用户故事地图写了一份具体的产品设计文档，文档包含了所有已知需要的详细描述、页面的原型设计、跳转逻辑、版本的公布日期及对应的性能列表等，这些工作就有点画龙点睛了，因为咱们当初只有一个待验证的产品愿景，咱们还不能确定产品的方向是否正确、用户画像是否精确、需要是否能满足最终客户的须要等，咱们这时候做的这么一份具体的设计文档，很可能是用不上的。即便咱们强行应用这份文档，前期的保护老本也会十分高，这份文档就属于不能“发明价值”的文档，它会导致咱们交付文档的总价值升高。如果咱们在做完这份具体的产品设计文档当前，再分割一家出版社，将它编辑后印刷进去，这时候咱们通过这一系列的产品文档所播种的总价值（理论收益 - 投入老本），可能简直就是 0 了！
当然下面这张图我画的有点理想化了，写文档就像摸索客户的需要一样，在达到最高价值之前，咱们可能会走很多弯路，写很多不必要的文档，不过为了便于阐明，我假如从一开始咱们就在写那些能“发明价值”的文档。
那咱们怎样才能保障本人少走弯路，确保始终在写发明价值的文档呢？
四、怎么写出一份发明价值的麻利文档
一份文档是否能够为产品发明价值，能够通过以下 5W1H 的形式来判断：
4.1 WHO- 谁须要文档？
咱们在做产品布局时，都会先做个用户画像，以确定咱们的产品服务于哪些客户，用户画像能够帮忙团队从“以性能为核心”转向“以用户为核心”做产品设计。
咱们写文档的时候也是一样，在决定要写一份文档之前，咱们要首先思考到文档的使用者是谁？是客户、是用户、是产品人员、是开发人员还是公司领导？角色不同，对文档的需要可能也会不同，所以咱们只有首先确定了文档的使用者，才有可能写出满足客户须要的、发明价值的文档。
这里有个概念大家须要留神一下：咱们要确认的是文档的“使用者”，而不是“提出者”。这两者有什么区别呢？置信大家都听过一句话：“你妈感觉你冷”，文档的提出者就能够类比为妈妈，而文档的使用者能够类比为孩子——孩子冷不冷，只有孩子本人才晓得。
4.2 WHAT- 须要什么文档？
当有人跟你提出须要文档时，肯定是因为他的某些需要没有失去满足，那咱们须要提供什么样的文档能力满足客户的需要呢？这里记住 4 个准则。
- 首先，你提供的文档要抓住客户的痛点，否则客户必定会一直的要求你提供更多的文档。
- 其次，要客户十分具体地形容他对文档的需要，肯定不能承受泛泛而谈的需要。比方客户说“我要一份产品文档”，这个“产品文档”就太泛了，然而如果说“我要一份产品的原型图”就具体多了。
- 第三，要确定文档的载体，也就是具体模式，比方是 word，是 Axure 源文件，还是 HTML？
- 最初，通知客户你制作文档所需的工作量，你在文档上投入的任何工夫，你本都能够用在新性能的开发上的，你必须让客户意识到这点，这样客户才不至于无止境的提文档的要求。
一个举荐的做法是，把文档也当做是需要，排入到 Backlog 中，通过将文档视为需要，你能够将其工作量提供给利益相干方（可能不止文档的使用者）做参考，以此决定文档要不要写、写到什么水平。从根本上说，对文档的投资是一个商业决策，而不是技术决策：文档不应该为流程或规章制度而创立，文档应该为你的利益相关者而创立。
PS. 如果你所在的组织的确在为流程而写文档，这时能够关上《Scrum 指南》，翻到“Scrum Master 以多种形式服务于组织”一节，通知 Scrum Master，这正是他发挥作用的时刻！然而要留神一点，《Scrum 指南》中只说了 Scrum Master 要服务于本人的组织，如果另一个组织对你所在的组织有不合理的要求，比方你作为乙方在为甲方做一个我的项目，甲方强制要求你在每个里程碑节点的时候都要提供一堆文档，这一点就超出 Scrum Master 的管制范畴了。
4.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.4 HOW- 怎么提供？
上一节咱们聊到，咱们提供文档的目标是为了沟通和了解，为了更好的达到这个指标，咱们要怎么做呢？丛斌老师在他的《知行合一：实现价值驱动的麻利和精益开发》一书中给了一个沟通热度及其有效性的模型，如下图所示：
从上图能够看出，“有问题廓清环节”的沟通形式（邮件、电话、白板探讨等）在沟通热度和有效性方面都显著高于“无问题廓清环节”（录音、录像、纯文字等）的沟通形式，所以咱们应该优先选择“有问题廓清环节”的沟通形式，同时在沟通实现当前，依照客户的须要，及时整顿出适量的文档（比方电话的录音、白板的照片等）。然而是不是“无问题廓清环节”的沟通形式就一无是处了呢？也不肯定，在某些状况下，比方交换个体之间的间隔（无论是物理上的还是工夫上的）很大时，“无问题廓清环节”的沟通形式会是一个更好的抉择，这种沟通形式，就须要筹备大量的文字、语音或视频文档了。
4.5 WHEN- 何时提供？
麻利开发中需要治理常常采纳的策略是推延决策，创立麻利文档的工夫也遵循这个策略，咱们要尽可能的推延所有文档的创立工夫，如下图所示，只有在咱们理论须要的时候再去创立它们。例如，零碎概要文档最好是在一个版本的开发末期编写，因为只有在这时你才晓得你理论构建了什么。同样，大部分的经营反对文档也最好在我的项目生命周期的最初来写。然而，这并不意味着所有的文档都应该留到最初。团队应该在整个开发过程中为最初要交付的文档记录素材，这样你就不会失落要害信息。开发过程中记录的素材最好只是一些零散的信息，因为在最终交付之前，没必要对文档进行认真打磨。
在我的项目信息稳固后再撰写文档，你能够无效升高与文档相干的老本和危险：老本升高是因为你不会浪费时间去批改文档中曾经变动的信息；危险升高是因为你现有文档过期的可能性大大降低。如果你提前写完了文档，然而文档中蕴含的信息都还只是个布局，那么一旦信息发生变化，你就会面临批改文档甚至是从新编写文档的危险。换句话说，你不应该在我的项目晚期投入大量工夫来记录打算的想法，比方需要、设计等。相同，咱们最好等到我的项目的前期，等零碎曾经初具雏形，并确定好哪些信息对你真正有用的时候再去撰写文档。
这个实际的一种极其形式是等到你零碎上线后再写文档，这种形式的次要的长处是你写的都是已知的、稳固的内容（你曾经公布的软件）。不过这种做法有几个显著的毛病：
- 这时你很可能曾经遗记了某些决定背地的起因，如果这些起因对你很重要的话，这个问题会很重大。
- 你可能没有适合的人再去写文档了，因为他们可能曾经转向其余我的项目了。
- 你可能没有估算来做这项工作。
- 编写文档的志愿可能不复存在。
所以咱们应该尽可能的推延麻利文档的提供工夫，然而不要始终推延到我的项目完结了才写，同时咱们要在我的项目过程中时刻记录有用的素材。
4.6 WHERE- 从哪里开始？
后面说了这么多，很多人可能还是有一个纳闷，麻利文档到底应该要从哪开始写？尽管我在后面画了这么一张图：
然而这只是一个示例，我并不是倡议大家都依照“麻利开发方式”的示意来写。因为每个公司的我的项目类型、治理形式、规章制度可能都不一样，所以这一点是没法给出一个规范的实际办法的，我的倡议是从现状开始！可能有人看到这个答案就笑了：咱们当初就是在写一堆无用的文档，你让我从现状开始？
这里我要解释下我所说的“现状”的含意：现状不是指你们当初在写哪些文档，而是你们当初在应用哪些文档。比方你们在日常的开发过程中始终在用设计图、接口文档等，并在整个我的项目过程中放弃更新，那么这是一个很好的迹象，阐明这些材料都是很有价值的我的项目信息，你应该围绕着这些信息来编写文档。对于那些没有放弃更新或更新当前也根本无人问津的文档，这些文档很可能就是在为了流程而写，再继续编写这类文档就没有任何价值了。
所以从现状开始的含意是：你能够从团队始终在应用的我的项目信息开始写文档，而后在麻利迭代的过程中，也继续一直的迭代你的文档。
五、小结
如果麻利文档要用一句话来总结的话，那就是：在正确的工夫，找到正确的人，挖掘正确的需要，应用正确的办法，实现正确的文档！
起源：小船哥说麻利
作者：adoudou
申明：文章取得作者受权在 IDCF 社区公众号（devopshub）转发。优质内容共享给思否平台的技术伙伴，如原作者有其余思考请分割小编删除，致谢。
7 月每周四晚 8 点，【冬哥有话说】研发效力工具专场，公众号留言“研发效力”可获取地址
- 7 月 8 日，周文洋《微软 DevOps 工具链的 “ 爱恨情仇 ”（Azure DevOps）》
- 7 月 15 日，陈逊《复杂型研发合作模式下的效力晋升实际》
- 7 月 22 日，张扬《基础设施即代码的⾃动化测试摸索》
- 7 月 29 日，胡贤彬《自动化测试，如何做到「攻防兼备」？》
