敏捷軟件開發宣言 1 說「 可以工作的軟件重於面面俱到的文檔」，看到很多軟件團隊將其解釋成「不寫任何文檔」真是令人難以置信。其中的基本原理是，對最終用戶來說真正工作的軟件比一堆面面俱到的文檔有價值得多，但是很多團隊把敏捷宣言中的這句話當成了完全不寫任何文檔的借口。很遺憾，代碼不會講述完整的故事 ，缺少關於複雜軟件系統的輔助信息源會讓團隊在努力瀏覽代碼時被拖累。
1 http://agilemanifesto.org
我也堅信，軟件團隊有義務和代碼庫一起交付一些輔助文檔，特別是那些在外包或離岸合同下構建軟件的團隊。我見過IT咨詢組織交付高度複雜的軟件系統給客戶時甚至沒有一頁支持文檔，往往是因為團隊就沒有任何文檔。如果原來的軟件開發者離開了咨詢組織，新的團隊能否理解軟件的方方面面，它如何構建以及如何以契合原始架構的方式增強？那可憐的客戶怎麼辦？是不是應該只 交付給他們可工作的代碼庫？
問題是，當軟件團隊考慮文檔時，他們通常想到的是基於一個1990年代軟件架構文檔模板的龐大微軟Word文檔，其中還包括一個需要為他們的軟件支持的每一個用例繪製統一建模語言（UML）類圖的部分。幾乎沒有人喜歡閱讀這種類型的文檔，更別說寫了！我們需要一種不同的方法。我們應該考慮把輔助文檔作為一個不斷變化的旅遊指南，而不是一個綜合的靜態歷史片斷。但這樣的指南應該寫些什麼？