如果敏捷是反文檔的，爲什麼會發佈一個宣言？
2001年，17位軟件開發、測試人員（其中包括Ward Cunningham、Jim Highsmith、Alistair Cockburn以及Bob Martin）共同發佈了《敏捷宣言》，並正式提出敏捷開發方法，作爲傳統文檔驅動、重量級軟件開發過程的替代方案。《宣言》提出了以下基本原則：
- 個人和交互高於過程和工具
- 工作軟件勝過全面的文檔
- 客戶協作高於合同談判
- 響應變化而不是遵循計劃
似乎預見到這種簡單可能會導致誤解，《敏捷宣言》也對此進行了澄清：“也就是說，雖然右邊的東西有價值，但我們更看重左邊的東西。”
即便如此，業內對敏捷開發方法的誤解和困惑仍然存在。“over”被“instead of”所取代，原本《敏捷宣言》的意圖是“最好把更多的注意力放在軟件上，而不是把時間花在過於詳細的前期文檔上”，現在似乎變成了“讓我們完全拋棄文檔，並希望我們記住討論的所有事情。”
一、敏捷神話：“文檔並不重要”
採用傳統IT項目方法的團隊會在項目的早期階段定義並記錄需求。隨後，這些需求將會被提交給開發人員，開發人員收到需求後便立即開始實施。
雖然敏捷開發方法是作爲這種文檔驅動開發過程的替代方法而創建的，但它並不打算完全消除內部文檔。由於軟件開發在本質上是動態的，因此，敏捷開發更重視工作軟件而非綜合文檔。
敏捷開發方法中沒有任何內容會阻止團隊創建項目所需的文檔。事實上，在某些情況下，文檔是絕對需要的：將用戶故事添加到待辦事項列表中，以及創建流程圖、做會議記錄等。敏捷只是——敏捷只是建議在這方面團隊要聰明一點。
文檔應該“剛剛好”。太多或過於全面的文檔會浪費時間，而且開發人員很少相信詳細的文檔，因爲它通常與實際代碼不同步。另一方面，經驗表明，文檔太少始終是困擾溝通、學習和知識共享問題的根源。
二、投資敏捷文檔的原因
敏捷文檔的創建和維護對某些人來說是“不可避免的災難”，但對另一些人來說，這是一項愉快的任務。同樣，會有一些合理的理由讓你相信，值得在敏捷文檔上投入時間：
- 項目的利益相關者需要它。從根本上來說，創建文檔是一個業務決策，團隊將利益相關者的資源投入到文檔開發中，因此他們應該對是否以這種方式花費他們的錢有發言權。
- 支持與外部團隊的溝通。開發團隊總是位於同一地點是不可能的，並且讓利益相關者隨時待命也是不可行的。共享文檔通常是與偶爾的面對面討論、電話會議、電子郵件和協作工具相結合的解決方案的一部分。
- 也不可能總是讓項目涉衆隨時待命。共享文檔通常與偶爾的面對面討論、電話會議、電子郵件和協作工具結合在一起，是解決方案的一部分。
- 支持組織記憶。敏捷建模的原則之一是“實現下一個努力是你的次要目標”，這意味着與“工作軟件是你的首要目標”的原則相平衡。這意味着，團隊在開發軟件時，還需要開發使用、操作、支持和維護軟件所需的支持文檔。
- 把事情想清楚。把想法寫在紙上的行爲可以幫助自己鞏固它們，並發現自己思維方式中的問題。那些在腦海中看起來清晰而直接的東西，往往會被證明是非常複雜的，所以可以先把它寫下來。
雖然以上所有的理由可能都是文檔化的合理理由，但我們總是問自己這樣一個問題：我們目前需要的最少可交付量是多少？
三、如何在敏捷中編寫文檔
1.敏捷文檔的4條原則
- 敏捷中的文檔是“可變的”，需要整個團隊協同維護。爲了充分利用我們在文檔上投入的時間，我們可以遵循一些簡單的原則：
- 確保它總是“剛剛好”。請記住，創建的任何文檔都必須在之後進行維護。如果文檔簡單、不復雜、不太詳細，就更容易理解和更新。
- 用“just in time”來寫。在記錄之前先耐心等待——這是避免積累錯誤和過時信息的最好方法。在需要的時候再生成文檔，而不是在需要之前生成。
- 將文檔放在一個容易獲取的地方。文檔只有在可訪問的情況下才有用，將產品文檔存儲在團隊成員可以輕鬆找到的地方。
- 與團隊合作。在敏捷團隊中維護文檔是一個協作過程，應該鼓勵每個團隊成員對此做出貢獻。
2.何時記錄
敏捷中工作軟件的迭代交付有效地取代了很多（儘管不是全部）全面的前期需求文檔。其理念是儘可能保持文檔的簡單和輕量級，特別是在項目的早期階段。那麼在什麼情況下值得在文檔中投入時間呢？
一個常見的敏捷實踐是儘可能推遲所有可交付文檔的創建，在實際需要交付文檔之前創建文檔。例如，系統概述和支持文檔最好在軟件開發生命週期（SDLC）的結束時編寫。從本質上講，這種方法是在等到信息最終確定後再捕獲它。
另一種敏捷文檔的策略是持續文檔化。在整個項目中編寫可交付文檔，在更新代碼的同時更新文檔。這種方法符合敏捷的方法，即持續生成潛在的可交付的解決方案。
然而，由於需求可能在項目的過程中不斷髮展，因此需要相當多的時間來讓可交付文檔的保持最新狀態。從敏捷的角度來看，這又是一份“沉重的負擔”。
在實踐中，敏捷通常會推遲編寫文檔，直到他們有時間這樣做，實際上，即使他們最初決定持續更新文檔，也會逐漸轉向文檔的後期實踐。
3.記錄什麼
- 敏捷文檔中可能用到的文檔示例包括案例研究、圖表、表格和站點地圖。以下是在項目過程中會考慮創建的一些文檔：
- 產品願景：它是對產品核心的描述，是對當前的成本估算、預期收益、風險、人員配備估算和計劃里程碑的總結。這一文檔的要求是：保持簡短，直切要點。
- 項目概述：這是與項目相關的關鍵信息的總結，例如主要用戶聯繫方式、技術和用於構建系統的工具等。將其作爲團隊新成員的起點，並在整個開發過程中對其進行維護。
- 設計決策：這是團隊在整個項目中做出的與設計和架構相關的關鍵決策的概述。
- 操作文檔：這通常是對系統所涉及的依賴項的描述，以及對備份過程的參考、故障排除指南等。運營部門可能會有此類文檔的標準格式。
- 需求文檔：它是對系統功能的概述，包括用例、用戶故事或基本用戶界面原型等。旨在將需求捕獲爲可執行規範。
- 支持文檔：這包括專門爲支持人員提供的培訓材料、故障排除指南等。與運營部門一樣，支持團隊可能有標準模板或示例來使用。
- 系統文檔：提供系統的概述，包括技術體系結構、業務體系結構和其他高級需求。系統文檔有助於確保關鍵信息的留存。
- 用戶文檔：它包括用戶參考手冊和支持指南。這一文檔的要求是保持簡單、易懂。如果需要採用大量的培訓來教會用戶如何使用該產品，那麼解決方案文檔的設計就是有缺陷的。
四、結論
“我們接受文檔，但不接受數百頁從未維護過以及很少使用的大部頭。”
敏捷開發方法絕不是反文檔的。它只是提醒團隊不要編寫多餘的文檔，並且在必要時儘可能保持文檔的簡單性。通過敲定某種格式和細節級別的，允許更改並能交付足夠價值的文檔，以保持團隊在正確的方向上前進。
往期文章：