> 原文出處：http://www.infoq.com/cn/articles/roadmap-agile-documentation
介紹一下我的朋友Jane和John。
John是一家大型公司的長期分析師，負責捕獲新的軟件產品及現有軟件產品的需求。他用SRS（軟件需求規格說明書）記錄所有客戶對正在開發或維護的特定產品的需求。
Jane是同一家公司的開發人員。她通常接收John的軟件需求規格說明書（SRS），而后開始對要實現的內容進行技術分析和設計。完成分析之后，她就開始寫代碼實現。
我的這兩個朋友John和Jane的需求文檔和設計文檔都需要經過審批；對于John來講，把需求文檔發給Jane之前需要經過審批，而對Jane來講，則是在開始寫代碼之前要經過審批。
最近，John和Jane所在的公司采用了敏捷方法來作項目管理和軟件研發，這使得他們的工作方式發生了改變。不需要制定大量的前期需求和設計，需求說明書和開發都被切成了小塊的信息，摒棄了使用多年的大篇幅文檔。開發人員的開發方式也發生了變化，鼓勵像實現之前先做測試設計和用較長的名字來命名函數等這樣的做法。
不出所料，John和Jane提出了一大堆的問題：
* 如果我們無法提前知道要開發什么，那我們怎么開始開發呢？
* 那些功能資料如果不記錄在往常所用的SRS中，那么記錄在哪里呢？
* 我們如何了解要開發的所有詳細信息？
* 用于未來維護的說明文檔和代碼放在哪里？
* 如果沒有寫文檔的階段，那么我們什么時候寫文檔呢？
在過去十年中，敏捷方法在項目管理和軟件開發中的應用經歷了迅速發展的階段，并預計將持續地增長。在向敏捷過渡的過程中，看似寬松的開發方式完全不同，做事不再那么傳統，為此，世界各地的許多人都會和John、Jane一樣拋出如上同樣的問題。
當公司開始過渡到敏捷理念的過程中，一些工作方式的差異都與文檔有關。
本文將重點講述為什么、什么時候、如何以及在哪里編制技術和功能文檔。
[TOC]
## 文檔編制與敏捷理念
敏捷宣言中宣稱的價值觀是：
個體和互動?高于?流程和工具?
工作的軟件?高于?詳盡的文檔?
客戶合作?高于?合同談判?
響應變化?高于?遵循計劃
盡管提到了文檔，但敏捷原則在如何編制文檔方面并沒有給出任何剛性的指導原則。
因此，在敏捷管理的項目中我們應該期待產出什么樣的文檔呢？
敏捷理念背后的原則是，強調為客戶實現價值。這就意味著我們應該把產品開發的時間花在能夠為客戶帶來價值的那部分，避免在幾乎沒有什么價值的任務上浪費時間。該原則也同樣適用于文檔的編制。
在傳統的瀑布方式中，文檔是一個預定義的階段，它需要花費大量的時間。過渡到敏捷則意味著我們必須重新思考編寫文檔的方式，以避免把時間浪費在價值具有爭議的交付成果上。
這是否意味著我們不需要編制任何文檔呢？其實不是這樣的。
另一個敏捷原則是適應變化。那就意味著我們不能提前做太多的計劃，因為事情在項目進行中會有所變化。所以，我們永遠專注的是適時的計劃。這一條也同樣適用于文檔。為了避免浪費時間，我們應該只在需要文檔時才去編寫它。
但是，我們如何知道它何時需要呢？
## 真的需要文檔嗎？-為什么需要文檔
如果你來自瀑布的領域，那么很自然就會帶過來定義大量文檔的習慣，但這樣會導致：
* 編寫了很多不必要的詳細信息。
* 編寫的是傳統的規格說明書，敏捷只是一個名字而已。
為了避免這個情況，有一些指導方針幫助我們決定是否真的需要編制文檔。
為避免在文檔上浪費時間，向每個相關的人問如下問題：
* 這個文檔是用來做什么？是支持開發嗎？還是提供功能的參考文獻？
* 文檔的目標受眾是誰？什么人？哪個部門的？他是客戶嗎？或者是未來的維護團隊？
* 這些目標受眾如何使用這篇文檔？是一個參考文獻嗎？還是一個手冊？
* 編制這些文檔需要多少成本？需要多少時間？由誰來完成？
決定是否需要文檔的一個關鍵因素是，只定義正好夠用的文檔。在干系人真正需要的和完整的內容之間尋找平衡點。不多不少，恰到好處。
## 何時，在哪，編制什么文檔
對為什么編制文檔和編制多少文檔達成共識之后，在開始編制之前還需要定義要編制什么樣的文檔。
### 什么樣的文檔
根據文檔的目標受眾來編制相應的文檔。教程？培訓材料？維護支持文檔？業務規則文檔？還是系統描述文檔？
在項目的每一階段規定需要什么樣的技術文檔和功能文檔，從而來確定編制什么文檔：
* 在項目開始之前，需要什么樣的文檔？
* 在項目中期 ，需要什么樣的文檔？
* 在產品開發完畢或者產品推出后，需要什么樣的文檔？
### 在哪
在一個易于訪問的并可不斷更新的資源庫中保存文檔對保持文檔的可用性非常有幫助。用Word文檔或類似的格式會讓其變得陳舊或過時。
隨著項目的滾動進行，文檔應當長期保持更新，保持文檔對目標受眾的有效性。
### 何時
不像在瀑布式開發所期待的那樣，在敏捷開發中沒有文檔階段。
因此，當功能以增量的方式開發時，文檔的編制也應該是增量的，與產品開發一起演進。
## 如何編制文檔
在這一點上我們應該決定：
* 編制剛好夠用的文檔。
* 編制什么文檔。
* 文檔存在哪里，如何保持有效性。
* 什么時候編制文檔。
在項目的每一個階段如何編制文檔呢，現在讓我來提供一些建議和最佳實踐。
### 項目啟動文檔
在項目初期階段，只需要少量的文檔，因為真正的工作就是如何開始。
當開始編制技術文檔時，定義你選定的兩個或者三個高層次的架構圖，并定義解決方案中需要實現的高層次組件。
在功能方面，用史詩（Epics）來定義產品需要開發的主要特征就可以了。
因為要用敏捷的方式管理項目，不要求預先設計，所以在這個階段，定義夠用的信息，讓團隊開始工作就足夠了。
### 項目文檔
在項目進行階段，隨著產品的增量開發，可能需要編制兩種類型的文檔：
**A****．**恰到好處的需求文檔-作為產品待辦事項列表（Product Backlog）的輸入。
**B****．要實現的**系統和業務邏輯-作為每個迭代的輸出。
每一種文檔都有它自己的目標受眾：
**目標受眾****A:?**團隊。
**目標受眾****B****：**干系人和最終的維護團隊。
這些文檔需要對這兩類目標受眾的需求給出回應。
**功能文檔**
用戶故事是敏捷管理項目中最常用的功能文檔。用戶故事匯聚了足夠的信息，告訴開發人員如何實現這些需求，它是用下面的格式描述的：
* 描述：用“作為，我想要，因此我可以”這樣的形式。
* 驗收標準：定義故事是否完成的標準，讓團隊和產品負責人對此達成一致。
在迭代計劃之前，用戶故事的需求描述必須經過干系人的認可，這意味著現在它們已經為計劃的迭代做好了準備，它們應該有可靠的信息來源（需求），開發人員知道要實現什么。這需要對目標受眾**A**提供足夠的信息。
當用戶故事正在開發中時，團隊可能會確定新的驗收標準，然會添加到用戶故事中。
記住，在敏捷中，用戶故事不應該是一小塊非常詳盡的需求描述，而是希望提供什么功能實現的指導方針，這是產品負責人和團隊之間未來合作要實現什么產品的承諾。
當用戶故事開發完成并被干系人接收之后，那么就可以認為它是已接收的了。這個時候，用戶故事需要從Product Backlog（需要實現的一系列功能需求描述列表）中挪到Product Increment（在迭代及所有之前的迭代中已完成的一系列產品代辦列表）。
當用戶故事以增量的方式完成時，目標受眾**B**所需要的文檔在下圖1中顯示。
**技術文檔**
在研發階段，開發人員需要運用一些公認的最佳實踐（作為敏捷開發方法的一部分），例如測試驅動開發TDD（Test-Driven Development）和行為驅動開發BDD（Behavior-Driven Development），以及結構良好的代碼、非技術人員可讀等。這個需要提供描述代碼的技術文檔。
**最新的功能和技術文檔**
因為代碼是最新的業務規則和系統實現的最可靠來源，因此基于代碼本身是擁有有效文檔的最佳方式。
活文檔是實現它的一種方式。
活文檔或動態文檔是持續編輯和更新的文檔。活文檔的概念依賴于在代碼中集成的文檔，該文檔是基于驗收標準，用領域專用語言（Domain Specific Language）來寫的，例如用于Cucumber的Gherkin。通過工具來輔助活文檔的持續構建，寫在用戶故事中的驗收標準作為代碼的一部分已經實現了，并且以一種可讀的格式在更新的、典型的在線地址上輸出。
提供活文檔機制的一些工具包括：[Cucumber](http://cukes.info/)，[Concordion](http://concordion.org/)，[FitNesse](http://www.fitnesse.org/)，[SpecFlow](http://www.specflow.org/)，
[Pickles](http://www.nuget.org/packages/Pickles/)，以及其他。他們都值得一看。
## 項目后期文檔
由于文檔是隨著用戶故事的實現增量編制的，在開發周期結束和產品推出后，那些技術和功能文檔應該描述了所有的功能實現。
## 歸納
當決定需要編制多少文檔時，很重要一點是要定義多少文檔是剛好夠用的文檔。
圖2描繪了本文中所推薦的用來決定文檔編制的路線圖。
在確定了為什么、做什么、什么時候做、怎么做之后，就要用敏捷的方式定義編制文檔的最佳實踐，用敏捷軟件開發的技術和活文檔。
表格1中列出了每一階段推薦的文檔輸出內容。
| ?選項 | **項目前期文檔** | **項目中期文檔**| **項目后期（維護）文檔**|
|---|---|---|---|
| **技術** | 選擇的兩個或三個高層次架構圖 | 結構良好的代碼，無技術基礎人員易讀<br/>測試驅動開發 （TDD）<br/>行為驅動開發 （BDD）<br/>以代碼為文檔<br/>【一次一個用戶故事】 | 代碼作為技術文檔 |
| **功能** | 主要的史詩定義產品需要開發的主要特征 | 具有定義良好的用戶故事，清晰的驗收標準<br/>以驗收標準為文檔<br/>【一次一個用戶故事】 | 代碼作為活文檔 |
## 總結
如同我的兩個虛擬朋友Jane和John所經歷的一樣，對任何的團隊來說從傳統的瀑布式到敏捷開發的過渡都是一種挑戰。人們的工作方式已經沿用了幾十年，當發生轉變時，就會引發各種問題和質疑。
在所有這些由團隊協作方式的轉變（尤其是在思想意識上的轉變）而引起的問題和質疑中，文檔是一個主要的問題，這是其中變化最大的一個--從開發之前編制所有文檔變成同一階段幾乎不怎么寫文檔。
敏捷的基本原則并沒有說不需要任何文檔，只是提醒團隊應該注重給客戶交付的價值。在編制文檔的過程中，也應該考慮這一關鍵原則。
所以，編制文檔時請記住，只在需要的時候編制必要的文檔，不多也不少。
提醒你的團隊要適時地編制恰到好處的文檔。
## 關于作者
在大約二十年前，**Ester F. Gon?alves**作為一名開發人員和系統分析師開始了她的職業生涯。在最近的四年里，她決定研究IT的業務領域。她在敏捷管理的團隊中從事IT業務分析工作，成為了一名敏捷愛好者，研究敏捷方法論、系統和業務分析技術，撰寫和發表了多篇相關的文章和博客，偶爾在會議和研討會上發表這些主題的演講，并且渴求自己做得更好。
**查看英文原文**：[http://www.infoq.com/articles/roadmap-agile-documentation](http://www.infoq.com/articles/roadmap-agile-documentation)
