在分析敏捷開發(fā)中的文檔之前，我們要先搞清楚什么是“文檔”。
維基百科給出的解釋是：
具有三個基本屬性，即：知識性、記錄性、物質(zhì)性，它具有存貯知識、傳遞和交流信息的功能。
從這個定義我們可以知道：“文檔”可以理解為一切可以存貯知識、促進溝通、傳遞信息的有形或無形的資料。
弄清楚“文檔”的概念后，我們就可以繼續(xù)分析敏捷開發(fā)中的文檔了。
很多團隊在看到敏捷宣言的這句話以后：
工作的軟件高于詳細的文檔。
都會產(chǎn)生一個問題：既然軟件比文檔重要，那敏捷開發(fā)是不是可以不寫文檔了？
在這里我們就假設(shè)在軟件開發(fā)過程中是可以不寫任何文檔的，那我們?nèi)粘５墓ぷ鲌鼍翱赡軙沁@樣的：
- 迭代計劃會的時候，沒有任何書面的Backlog，PO把需求跟大家口述一遍，然后就直接開始開發(fā)；
- 迭代的過程中，沒有設(shè)計圖，沒有接口文檔，沒有測試用例，沒有bug記錄……；
- 每日站會的時候沒有看板，每個人都在口述自己昨天做了啥、今天要做啥，但是沒人能清楚地知道總共要做多少功能，做了多少功能，還剩多少功能；
- 需求的改動全靠口頭通知，請假或未出席會議的人全憑猜；
- PO對故事進行驗收的時候，因為沒有可視化的文檔，導(dǎo)致開發(fā)團隊做的東西根本不是他想要的，不停地返工；
- 評審會上，因為bug太多，新功能演示頻頻翻車，客戶不歡而散；
- 回顧會上，SM發(fā)現(xiàn)沒有任何客觀數(shù)據(jù)可供回顧的，于是大家隨便聊點不疼不癢的話題，散會；
- 項目勉強上線，沒有用戶手冊，沒有運維文檔，無人會使用，沒人能維護；
看完上面的描述，有些場景是不是似成相識？大家是不是覺得有些文檔還是很有必要的？寫很多詳細的文檔不合適，但是完全不寫文檔更不合適！文檔不僅可以讓我們開發(fā)過程中的溝通更順暢、進度更透明、變更可追蹤、bug有記錄， 還可以讓我們交付的產(chǎn)品更便于維護、使用和修改，可以有效延長產(chǎn)品的壽命。可以毫不夸張的說，文檔就是產(chǎn)品的一部分！那既然文檔如此重要，我們在敏捷開發(fā)中要寫多少文檔呢？之前我一直糾結(jié)于敏捷開發(fā)到底要寫多少文檔的問題，后來我在第N次閱讀《Scrum指南》的時候，看到了Scrum的定義：
Scrum 是一個輕量的框架，它通過提供針對復(fù)雜問題的自適應(yīng)解決方案來幫助人們、團隊和組織創(chuàng)造價值。
最新版的Scrum指南將Scrum的目的從“最高價值的產(chǎn)品”改成了“創(chuàng)造價值”，從上一節(jié)的描述我們知道，文檔是敏捷開發(fā)的一部分，那我們在敏捷開發(fā)中寫的文檔有沒有在“創(chuàng)造價值”呢？我們通過文檔所收獲的價值，可能跟圖1類似：理想情況下，在沒有任何文檔的時候，寫得越多（支出），收獲就越多（收入），我們所獲得的價值（利潤）也越高（利潤=收入-支出）。但是超過某個價值最高點，我們再寫更多的文檔（追加投資），可能就不再產(chǎn)生明顯的收益了（追加投資產(chǎn)生的收入<追加的投資），也就是我們撰寫的新文檔已經(jīng)不能“創(chuàng)造價值”了，這時我們獲得的價值總額開始下降。此時再繼續(xù)寫下去的話，最終會達到收支平衡點，這時我們所交付的全部文檔，已經(jīng)不產(chǎn)生任何價值了，即我們通過寫文檔所獲得的收入，已經(jīng)跟我們的支出一樣多了。如果一份文檔已經(jīng)處于價值最高點了（或者已經(jīng)越過價值最高點了），再寫更多的文檔就不能再“創(chuàng)造價值”了，這顯然是一種浪費，一份文檔一旦已經(jīng)實現(xiàn)了它的預(yù)期目標，再對它做再多的投資只會是畫蛇添足。我們用產(chǎn)品文檔來舉個例子：我們在規(guī)劃一個新產(chǎn)品時，一份產(chǎn)品愿景文檔是非常有必要的，因為它可以清晰的指明產(chǎn)品的定位及未來的發(fā)展方向；如果我們再根據(jù)這份產(chǎn)品愿景文檔，整理出一份用戶故事地圖，這也是十分有用的，因為它對于用戶的畫像、功能模塊的劃分、功能迭代的規(guī)劃等都是很有幫助的。但是如果我們再進一步，根據(jù)用戶故事地圖寫了一份詳細的產(chǎn)品設(shè)計文檔，文檔包括了所有已知需求的詳細描述、頁面的原型設(shè)計、跳轉(zhuǎn)邏輯、版本的發(fā)布日期及對應(yīng)的功能列表等，這些工作就有點畫蛇添足了，因為我們現(xiàn)在只有一個待驗證的產(chǎn)品愿景，我們還不能確定產(chǎn)品的方向是否正確、用戶畫像是否準確、需求是否能滿足最終客戶的需要等，我們這時候做的這么一份詳細的設(shè)計文檔，很可能是用不上的。即使我們強行使用這份文檔，后期的維護成本也會非常高，這份文檔就屬于不能“創(chuàng)造價值”的文檔，它會導(dǎo)致我們交付文檔的總價值降低。如果我們在做完這份詳細的產(chǎn)品設(shè)計文檔以后，再聯(lián)系一家出版社，將它編輯后印刷出來，這時候我們通過這一系列的產(chǎn)品文檔所收獲的總價值（實際收益-投入成本），可能幾乎就是0了！當然上面這張圖我畫的有點理想化了，寫文檔就像探索客戶的需求一樣，在達到最高價值之前，我們可能會走很多彎路，寫很多不必要的文檔，不過為了便于說明，我假設(shè)從一開始我們就在寫那些能“創(chuàng)造價值”的文檔。那我們怎樣才能保證自己少走彎路，確保一直在寫創(chuàng)造價值的文檔呢？四、怎樣寫出一份創(chuàng)造價值的敏捷文檔
一份文檔是否可以為產(chǎn)品創(chuàng)造價值，可以通過以下5W1H的方式來判斷：
我們在做產(chǎn)品規(guī)劃時，都會先做個用戶畫像，以確定我們的產(chǎn)品服務(wù)于哪些客戶，用戶畫像可以幫助團隊從“以功能為中心”轉(zhuǎn)向“以用戶為中心”做產(chǎn)品設(shè)計。我們寫文檔的時候也是一樣，在決定要寫一份文檔之前，我們要首先考慮到文檔的使用者是誰？是客戶、是用戶、是產(chǎn)品人員、是開發(fā)人員還是公司領(lǐng)導(dǎo)？角色不同，對文檔的需求可能也會不同，所以我們只有首先確定了文檔的使用者，才有可能寫出滿足客戶需要的、創(chuàng)造價值的文檔。這里有個概念大家需要注意一下：我們要確認的是文檔的“使用者”，而不是“提出者”。這兩者有什么區(qū)別呢？相信大家都聽過一句話：“你媽覺得你冷”，文檔的提出者就可以類比為媽媽，而文檔的使用者可以類比為孩子——孩子冷不冷，只有孩子自己才知道。當有人跟你提出需要文檔時，一定是因為他的某些需求沒有得到滿足，那我們需要提供什么樣的文檔才能滿足客戶的需求呢？這里記住4個原則。- 首先，你提供的文檔要抓住客戶的痛點，否則客戶肯定會不斷的要求你提供更多的文檔。
- 其次，要客戶非常具體地描述他對文檔的需求，一定不能接受泛泛而談的需求。比如客戶說“我要一份產(chǎn)品文檔”，這個“產(chǎn)品文檔”就太泛了，但是如果說“我要一份產(chǎn)品的原型圖”就具體多了。
- 第三，要確定文檔的載體，也就是具體形式，比如是word，是Axure源文件，還是HTML？
- 最后，告訴客戶你制作文檔所需的工作量，你在文檔上投入的任何時間，你本都可以用在新功能的開發(fā)上的，你必須讓客戶意識到這點，這樣客戶才不至于無止境的提文檔的要求。
一個推薦的做法是，把文檔也當做是需求，排入到Backlog中，通過將文檔視為需求，你可以將其工作量提供給利益相關(guān)方（可能不止文檔的使用者）做參考，以此決定文檔要不要寫、寫到什么程度。從根本上說，對文檔的投資是一個商業(yè)決策，而不是技術(shù)決策：文檔不應(yīng)該為流程或規(guī)章制度而創(chuàng)建，文檔應(yīng)該為你的利益相關(guān)者而創(chuàng)建。PS. 如果你所在的組織確實在為流程而寫文檔，這時可以打開《Scrum指南》，翻到“Scrum Master 以多種方式服務(wù)于組織”一節(jié)，告訴Scrum Master，這正是他發(fā)揮作用的時刻！但是要注意一點，《Scrum指南》中只說了Scrum Master要服務(wù)于自己的組織，如果另一個組織對你所在的組織有不合理的要求，比如你作為乙方在為甲方做一個項目，甲方強制要求你在每個里程碑節(jié)點的時候都要提供一堆文檔，這一點就超出Scrum Master的控制范圍了。為什么要寫這個文檔？撰寫文檔肯定是為了有所回報（創(chuàng)造價值）：可能是為了推銷產(chǎn)品（用戶手冊、售后指南等），也有可能是為了降低溝通成本（產(chǎn)品原型文檔、接口文檔等），也有可能純粹是為了通過某個流程（比如你作為乙方為了通過甲方的驗收）。但不管怎么樣，在寫任何類型的文檔前都要先搞清楚其背后的原因：客戶現(xiàn)在是如何做的、為什么需要新的文檔、他們希望如何使用新的文檔、有了新的文檔以后會有哪些收益等等。這里需要注意一點，不管客戶的真實需要是什么，大多數(shù)情況下，我們寫文檔的目的都是為了溝通，而溝通的主要目的是理解！知道了這個邏輯以后，我們可能就不會再醉心于完善的、精美的文檔了，因為文檔只是一個工具，溝通和理解才是目的！看完了前面3條：“Who-What-Why”，你有沒有覺得這個結(jié)構(gòu)有點熟悉？沒錯，就是用戶故事的3要素：As a 【role（Who）】, I want 【function（What）】, so that 【business value（Why）】.用戶故事通過這3個要素，就能保證做出來的功能是有價值的，那我們要寫的文檔是不是也可以只通過這3個要素來判斷有沒有價值呢？用戶故事只要3個要素就能把一個事情說的明白，是因為用戶故事有幾個隱含的條件：軟件的解決方案是Scrum團隊和利益相關(guān)方在Sprint計劃會上集體討論出來的（How），使用者是通過APP或web使用軟件的（Where），軟件中發(fā)生的事情都是在使用期間或預(yù)期時間（比如鬧鐘）發(fā)生的（When）。但是敏捷開發(fā)中的文檔，是沒有這些隱含條件的，所以我們還是需要繼續(xù)探索5W1H中剩下的3個要素的。上一節(jié)我們聊到，我們提供文檔的目的是為了溝通和理解，為了更好的達到這個目標，我們要怎么做呢？叢斌老師在他的《知行合一：實現(xiàn)價值驅(qū)動的敏捷和精益開發(fā)》一書中給了一個溝通熱度及其有效性的模型，如下圖所示：從上圖可以看出，“有問題澄清環(huán)節(jié)”的溝通方式（郵件、電話、白板討論等）在溝通熱度和有效性方面都明顯高于“無問題澄清環(huán)節(jié)”（錄音、錄像、純文字等）的溝通方式，所以我們應(yīng)該優(yōu)先選擇“有問題澄清環(huán)節(jié)”的溝通方式，同時在溝通完成以后，按照客戶的需要，及時整理出適量的文檔（比如電話的錄音、白板的照片等）。但是是不是“無問題澄清環(huán)節(jié)”的溝通方式就一無是處了呢？也不一定，在某些情況下，比如交流個體之間的距離（無論是物理上的還是時間上的）很大時，“無問題澄清環(huán)節(jié)”的溝通方式會是一個更好的選擇，這種溝通方式，就需要準備大量的文字、語音或視頻文檔了。敏捷開發(fā)中需求管理經(jīng)常采用的策略是推遲決策，創(chuàng)建敏捷文檔的時間也遵循這個策略，我們要盡可能的推遲所有文檔的創(chuàng)建時間，如下圖所示，只有在我們實際需要的時候再去創(chuàng)建它們。例如，系統(tǒng)概要文檔最好是在一個版本的開發(fā)末期編寫，因為只有在這時你才知道你實際構(gòu)建了什么。同樣，大部分的運營支持文檔也最好在項目生命周期的最后來寫。但是，這并不意味著所有的文檔都應(yīng)該留到最后。團隊應(yīng)該在整個開發(fā)過程中為最后要交付的文檔記錄素材，這樣你就不會丟失關(guān)鍵信息。開發(fā)過程中記錄的素材最好只是一些零散的信息，因為在最終交付之前，沒必要對文檔進行仔細打磨。在項目信息穩(wěn)定后再撰寫文檔，你可以有效降低與文檔相關(guān)的成本和風(fēng)險：- 成本降低是因為你不會浪費時間去修改文檔中已經(jīng)變化的信息；
- 風(fēng)險降低是因為你現(xiàn)有文檔過時的可能性大大降低。
如果你提前寫完了文檔，但是文檔中包含的信息都還只是個規(guī)劃，那么一旦信息發(fā)生變化，你就會面臨修改文檔甚至是重新編寫文檔的風(fēng)險。換句話說，你不應(yīng)該在項目早期投入大量時間來記錄計劃的想法，比如需求、設(shè)計等。相反，我們最好等到項目的后期，等系統(tǒng)已經(jīng)初具雛形，并確定好哪些信息對你真正有用的時候再去撰寫文檔。這個實踐的一種極端方式是等到你系統(tǒng)上線后再寫文檔，這種方式的主要的優(yōu)點是你寫的都是已知的、穩(wěn)定的內(nèi)容（你已經(jīng)發(fā)布的軟件）。不過這種做法有幾個明顯的缺點：- 這時你很可能已經(jīng)忘記了某些決定背后的原因，如果這些原因?qū)δ愫苤匾脑?，這個問題會很嚴重。
- 你可能沒有合適的人再去寫文檔了，因為他們可能已經(jīng)轉(zhuǎn)向其他項目了。
所以我們應(yīng)該盡可能的推遲敏捷文檔的提供時間，但是不要一直推遲到項目結(jié)束了才寫，同時我們要在項目過程中時刻記錄有用的素材。前面說了這么多，很多人可能還是有一個疑惑，敏捷文檔到底應(yīng)該要從哪開始寫？雖然我在前面畫了這么一張圖：但是這只是一個示例，我并不是建議大家都按照“敏捷開發(fā)方式”的示意來寫。因為每個公司的項目類型、管理方式、規(guī)章制度可能都不一樣，所以這一點是沒法給出一個標準的實踐方法的，我的建議是從現(xiàn)狀開始！可能有人看到這個答案就笑了：我們現(xiàn)在就是在寫一堆無用的文檔，你讓我從現(xiàn)狀開始？這里我要解釋下我所說的“現(xiàn)狀”的含義：現(xiàn)狀不是指你們現(xiàn)在在寫哪些文檔，而是你們現(xiàn)在在使用哪些文檔。比如你們在日常的開發(fā)過程中一直在用設(shè)計圖、接口文檔等，并在整個項目過程中保持更新，那么這是一個很好的跡象，說明這些資料都是很有價值的項目信息，你應(yīng)該圍繞著這些信息來編寫文檔。對于那些沒有保持更新或更新以后也基本無人問津的文檔，這些文檔很可能就是在為了流程而寫，再持續(xù)編寫這類文檔就沒有任何價值了。所以從現(xiàn)狀開始的含義是：你可以從團隊一直在使用的項目信息開始寫文檔，然后在敏捷迭代的過程中，也持續(xù)不斷的迭代你的文檔。如果敏捷文檔要用一句話來總結(jié)的話，那就是：在正確的時間，找到正確的人，發(fā)掘正確的需求，使用正確的方法，完成正確的文檔！
IDCF DevOps黑客馬拉松，獨創(chuàng)端到端DevOps體驗，精益創(chuàng)業(yè)+敏捷開發(fā)+DevOps流水線的完美結(jié)合，2021年僅有的3場公開課，數(shù)千人參與并一致五星推薦的金牌訓(xùn)練營，追求卓越的你一定不能錯過！
