在今年與多個軟體開發單位的交流中，補文件的問題多次提到，試圖通過本文談談文件的價值，如何寫剛剛好的文件。

軟體開發所需要的文件在傳統的瀑布型生命週期下典型的有：開發計劃，需求規格說明書，設計書（有分成基本設計書、詳細設計書；也有分成High Level Design、Low Level Design；或者概要設計、詳細設計), 測試計劃（測試用例），測試報告，結題報告。其中的需求規格說明書和設計書是過程中最重要的兩份文件，往往多達數十頁，甚至數百頁。 後期，文件與實際軟體的一致性問題是比較突出的，往往出現軟體已經修改，而文件還沒有修改，兩者不一致。

敏捷開發針對這種情況提出了“可用的軟體 重於 完備的文件”，提出文件要Just enough。

那麼到底如何Just enough？ Just enough的對比是什麼呢？

大而化之，可以將文件的“Just enough”歸納到三種不同的極端需要：

1，通過文件，只要讓明天加入這個團隊的新人瞭解所要知道的內容就行了，不在文件中的內容，團隊老成員會通過諸如結對、協作等等方式告訴新人；

2，通過文件，可以處理當前專案結束後的維護，或者是後續跟進專案。

管理層和敏捷團隊自身可以考察團隊的穩定性，專案所處階段來判斷需要什麼樣的文件。如果團隊成員離職率高，文件需要就大，如果專案處於晚期階段，那麼要考慮專案結束後團隊去向，如果團隊會解散，那麼文件需求顯然，如果團隊會留下，那麼文件還是可以少些。因此這個問題是可以處理的。

3，客戶需要的文件，這個沒啥說的，客戶付錢要文件，當然要寫了。

從這3種情況來回看需求文件和設計文件，就會發現，“真的不用寫這麼多文件”。厚達100頁的需求，讓新人讀一遍都是一件煩人的事，而且新人也未必理解。如果軟體已經執行，介面做得友好，新人執行軟體來理解需求，效果比讀文字可要好的多，甚至給使用者的使用說明書都可以寫得簡短些。

有一個常見的情況：就是補文件。這種情況是軟體已經開發出來了，但由於規章制度等等原因的要求，要求補出文檔。

我們可以反思這個問題：既然沒有文件的情況下，軟體都開發出來了，為什麼還需要補文件？ 是不是可以修改開發流程，取消原來的寫文件環節？

如果原因是“所補的文件是使用者使用手冊，使用者在使用中是需要的”，這個補的文件顯然是有價值的。

如果原因是“所補的文件是需求規格說明書和設計書，沒有這個，XXX部不讓結題”，這個看起來就沒有價值，從流程上取消文件環節也不妨礙軟體開發。

如果原因是“合同規定了有這些文件，不寫，拿不到尾款”，這個沒啥說的，為了錢也要寫，問題是下次合同時要麼取消這個文件條款，要麼按合同要求及時寫文件。

如果原因是“所補的文件是需求說明，沒有這個就沒法對應測試用例，測試不能保證完整性”，軟體已經開發出來了，已經可以運行了，也有使用說明，那麼測試用例已經可以設計，測試已經可以開展了。測試用例沒有必要一定對應需求的文字了。 執行的軟體+使用說明 本身可以理解為需求的一種表達形式。

如果“我們後續修復缺陷，都是直接查程式碼，從來不看老需求和老設計”，那麼文件的作用幾乎沒有了。

軟體快速出來，反而符合敏捷12條原則中的第1條"我們重視通過儘早、連續的提供有價值的軟體來滿足顧客。"

因此補文件還是要看文件的價值所在，沒有價值的文件是不值得補的。文件的價值主要分2類：1，滿足客戶需要；2，幫助後續維護。

從軟體開發本身來說，文件大多是不值得補的。如果一個組織出現大量補文件的情況，那肯定意味著這個組織的軟體開發流程可以調整了，簡單可行的思路是：如果文件是有價值的，那麼應當及時書寫；如果文件是沒有價值的，取消文件環節。

作者：張克強