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

軟件開發所需要的文檔在傳統的瀑布型生命周期下典型的有：開發計劃，需求規格說明書，設計書（有分成基本設計書、詳細設計書；也有分成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，幫助后續維護。

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

作者：張克強

blog:???http://blog.csdn.net/zhangmike??? ?允許全文轉載。