一、什么是“文檔”

在分析敏捷開發中的文檔之前，我們要先搞清楚什么是“文檔”。

維基百科給出的解釋是：具有三個基本屬性，即： 知識性、 記錄性、 物質性，它具有存儲知識、傳遞和交流信息的功能。

從這個定義我們可以知道：“文檔”可以理解為一切可以存貯知識、促進溝通、傳遞信息的有形或無形的資料。弄清楚“文檔”的概念后，我們就可以繼續分析敏捷開發中的文檔了。

二、敏捷文檔≠不寫文檔

很多團隊在看到敏捷宣言的這句話以后： 工作的軟件高于詳細的文檔。

都會產生一個問題：既然軟件比文檔重要，那敏捷開發是不是可以不寫文檔了？

在這里我們就假設在軟件開發過程中是可以不寫任何文檔的，那我們日常的工作場景可能會是這樣的：

• 迭代計劃會的時候，沒有任何書面的Backlog，PO把需求跟大家口述一遍，然后就直接開始開發；
• 迭代的過程中，沒有設計圖，沒有接口文檔，沒有測試用例，沒有bug記錄……；
• 每日站會的時候沒有看板，每個人都在口述自己昨天做了啥、今天要做啥，但是沒人能清楚地知道總共要做多少功能，做了多少功能，還剩多少功能；
• 需求的改動全靠口頭通知，請假或未出席會議的人全憑猜；
• PO對故事進行驗收的時候，因為沒有可視化的文檔，導致開發團隊做的東西根本不是他想要的，不停地返工；
• 評審會上，因為bug太多，新功能演示頻頻翻車，客戶不歡而散；
• 回顧會上，SM發現沒有任何客觀數據可供回顧的，于是大家隨便聊點不疼不癢的話題，散會；
• 項目勉強上線，沒有用戶手冊，沒有運維文檔，無人會使用，沒人能維護；
• 項目卒。

看完上面的描述，有些場景是不是似成相識？大家是不是覺得有些文檔還是很有必要的？寫很多詳細的文檔不合適，但是完全不寫文檔更不合適！

文檔不僅可以讓我們開發過程中的溝通更順暢、進度更透明、變更可追蹤、bug有記錄，還可以讓我們交付的產品更便于維護、使用和修改，可以有效延長產品的壽命?？梢院敛豢鋸埖恼f，文檔就是產品的一部分！那既然文檔如此重要，我們在敏捷開發中要寫多少文檔呢？

三、敏捷文檔＝創造價值的文檔

之前我一直糾結于敏捷開發到底要寫多少文檔的問題，后來我在第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-從哪里開始？
前面說了這么多，很多人可能還是有一個疑惑，敏捷文檔到底應該要從哪開始寫？雖然我在前面畫了這么一張圖：

但是這只是一個示例，我并不是建議大家都按照“ 敏捷開發方式”的示意來寫。因為每個公司的項目類型、管理方式、規章制度可能都不一樣，所以這一點是沒法給出一個標準的實踐方法的，我的建議是 從現狀開始！可能有人看到這個答案就笑了：我們現在就是在寫一堆無用的文檔，你讓我從現狀開始？

這里我要解釋下我所說的“現狀”的含義： 現狀不是指你們現在在寫哪些文檔，而是你們現在在使用哪些文檔。比如你們在日常的開發過程中一直在用設計圖、接口文檔等，并在整個項目過程中保持更新，那么這是一個很好的跡象，說明這些資料都是很有價值的項目信息，你應該圍繞著這些信息來編寫文檔。對于那些沒有保持更新或更新以后也基本無人問津的文檔，這些文檔很可能就是在為了流程而寫，再持續編寫這類文檔就沒有任何價值了。

所以從現狀開始的含義是： 你可以從團隊一直在使用的項目信息開始寫文檔，然后在敏捷迭代的過程中，也持續不斷的迭代你的文檔。

五、小結

如果敏捷文檔要用一句話來總結的話，那就是： 在正確的時間，找到正確的人，發掘正確的需求，使用正確的方法，完成正確的文檔！