理想中的文檔
在瀑布式開發(fā)方式下疼阔，我們會接觸如下幾類文檔：
| 名稱 | 內(nèi)容 | 目的 | 編寫人員 |
|---|---|---|---|
| 需求說明 | 需求背景惨撇、目的况毅、描述导犹、指標 | 描述客戶需求 | 需求分析人員 |
| 概要設計（系統(tǒng)設計） | 為實現(xiàn)需求而分解的軟件模塊以及之間的交互、接口絮吵、流程 | 將客戶需求初步分解為軟件需求 | 軟件架構(gòu)師 |
| 詳細設計 | 對概要設計進行細節(jié)補充弧烤，如類圖，異常流程 | 指導進一步編碼 | 開發(fā)工程師 |
| 測試用例 | 按條目整理的測試場景和用例 | 指導測試執(zhí)行 | 測試工程師 |
需求蹬敲、測試暇昂、開發(fā)在各自的環(huán)節(jié)輸出不同的文檔，如果文檔能將期望描述的內(nèi)容準確無誤的表述清楚伴嗡，看起來也是一個能自圓其說的流程急波。
現(xiàn)實中的文檔
理想雖然豐滿，現(xiàn)實卻往往骨感瘪校。在實際的軟件開發(fā)活動中澄暮，理想中的文檔面臨著下面這些挑戰(zhàn)：
- 軟件開發(fā)活動高度抽象名段，客戶需求往往又隱藏很多細節(jié)，用文字的形式描述清楚的的難度很大
- 寫文檔的人表達能力有限泣懊，軟件開發(fā)行業(yè)絕大多數(shù)都是理工男（連理工女都很少）伸辟，寫文檔本就是弱項
- 讀文檔的人對自己的理解能力總是莫名自信，即使文檔沒有說清楚馍刮，開發(fā)人員總是傾向于按照自己的理解去做
- 當需求或設計變更時信夫，文檔的更新往往不及時甚至是不更新
- 文檔分散在多人的電腦中，即使作者自己及時更新了文檔卡啰，也很難做到讓所有人同步更新
文檔所帶來的溝通成本
編寫文檔的本意是為了在開發(fā)環(huán)節(jié)的各個階段和角色之間傳遞信息静稻，降低溝通的成本，而現(xiàn)實中文檔到底有沒有降低溝通成本呢匈辱？比如說下面這個場景振湾，看著是不是覺得很眼熟：
- 測試人員發(fā)現(xiàn)了一個問題，于是提交一個bug
- 開發(fā)人員認為需求就是這么寫的亡脸，不是bug押搪，兩邊一通PK沒有結(jié)果，找需求人員確認
- 需求分析人員之前沒考慮到這個細節(jié)梗掰，于是重新定義了這個細節(jié)的處理方式嵌言，在他看來只需要稍作修改就可以了
- 開發(fā)人員分析當前的架構(gòu)hold不住，于是只好重新推翻之前的代碼再來一次
- 代碼修改完畢及穗，但設計文檔忘記更新摧茴，代碼和文檔不同步
有豐富經(jīng)驗且善于總結(jié)經(jīng)驗的開發(fā)人員都知道 “細節(jié)是魔鬼” ，在我們依賴文檔而不是更加 直接 和 實時 的方式進行溝通時埂陆，很有可能在溝通的環(huán)節(jié)我們就丟失了部分細節(jié)苛白，到最后引入了額外的成本，有時候還是高額的成本焚虱。
可能有些同學會說购裙，只要我們提升寫文檔的能力（比如金字塔）不就可以解決這個問題么？的確鹃栽，理想情況下只要文檔能夠充分的體現(xiàn)作者的意圖躏率，覆蓋所有的細節(jié)，那整個開發(fā)流程也沒有問題民鼓，但現(xiàn)實情況是這很困難薇芝，這個領(lǐng)域是作家、寫手才擅長的丰嘉，技術(shù)人員能夠往這個方向努力夯到，個別技術(shù)人員也能達到比較高的水準，但很難讓技術(shù)人員群體在整體上達到比較高的水準饮亏。而且文檔還有其他的問題耍贾，我們繼續(xù)往下看阅爽。
文檔的價值有多大？
組織怎么看文檔
CMM的流程定義和階段產(chǎn)物能夠給組織和公司帶來安全感（特別是規(guī)模比較大荐开，比較成熟的公司）付翁，看起來只要我們把各種文檔寫好，我們就能夠得到一個可控的開發(fā)過程晃听，項目的里程碑就能夠按部就班的達成胆敞，另外，文字化后的知識也更加適合積累和擴散杂伟。
我見過很多項目經(jīng)理確實是相信——只要我們輸出了需求分析文檔，那肯定是做了充分的需求分析的仍翰，只要我們輸出了詳細設計文檔赫粥，那肯定是進行了全面的方案設計和評審，或者說予借，即使不是那么充分和全面越平，至少還是有在做，總比沒有做要強灵迫。
一次實際的文檔交付
印象最深的一次秦叛，為了實現(xiàn)一個非常明確的小需求，提交的文檔有需求說明瀑粥、需求分析挣跋、概要設計、詳細設計狞换、測試用例等好幾份文檔（這種非常明確的小型需求也會讓開發(fā)人員直接進行需求分析）避咆，每一個文檔都有固定模板，需要進行評審修噪，提交評審記錄并添加版本說明查库，而最后實際修改的代碼不超過10行（還需要提交代碼走查記錄），這些文檔最后會提交svn黄琼，然后就沒有然后了樊销，這些文檔就這么安靜的塞在一臺不知道在哪的硬盤中，絕大多數(shù)的文檔不會有人再重新打開看一眼脏款，或者即使有人重新打開來看围苫，文檔內(nèi)容和最新的代碼已經(jīng)完全沒有任何聯(lián)系了！
開發(fā)人員怎么看文檔
以前看到過一個例子弛矛，大概意思是某監(jiān)獄有一種懲罰犯人的方式够吩，重復讓犯人把磚塊從A搬到B然后再從B搬到A，一直重復下去丈氓，犯人會在體力耗盡之前先精神崩潰周循。讓開發(fā)人員反復從事于這些文檔工作大概就是類似效果强法！
但是不要忘了，程序員可是這個世界上頭腦最聰明的一撥人湾笛，碰到這種情況程序員會怎么處理饮怯？編唄！代碼先寫嚎研，程序先調(diào)蓖墅，等所有事情做完了，不是要需求和設計文檔嗎临扮，照著代碼寫唄论矾，什么流程圖、交互圖杆勇，照著代碼實現(xiàn)畫唄贪壳，還要求評審記錄和修改記錄是吧，寫的時候隨便寫幾個錯別字蚜退，故意留幾個小章節(jié)先不寫闰靴，等評審的時候就把這些錄為評審記錄嘛……所以，雖然理想的瀑布式開發(fā)模式下需求分析和設計以及評審要求在最前面钻注，可是實際落地的時候呢蚂且，根本也不是那么回事！這種后補的文檔既沒有起到幫助分析需求的作用幅恋，也沒有起到指導開發(fā)的作用杏死，毫無價值可言，大家都知道是怎么回事捆交，可偏偏還沒有人說破识埋，不僅僅是對這世界上最聰明頭腦的浪費，還是對程序員良知的折磨零渐，如果這不是反人類窒舟，那是什么？
文檔還需不需要诵盼？
既然文檔不能進行有效的溝通惠豺，也毫無價值可言，那我們是不是不需要文檔了呢风宁？很多剛剛轉(zhuǎn)型敏捷的團隊真的就會這么做洁墙，將所有的文檔工作全部廢棄，剛開始的時候覺得挺好戒财，終于擺脫煩人的文檔工作了热监，但是過一段時間之后又發(fā)現(xiàn)還是不行，不寫文檔的話很多事情無據(jù)可查饮寞，A 說我們當時說好了要按這個方式實現(xiàn)的孝扛，結(jié)果 B 說不對列吼，明明是另一個方式，看起來沒有文檔也不行……
其實“需不需要寫文檔苦始？”這個問題是個偽命題寞钥，文檔肯定是需要的，即使是在敏捷宣言里面也沒有否定文檔的價值陌选，真正的問題是“那些內(nèi)容需要寫文檔理郑？”
哪些內(nèi)容需要些文檔
原則很簡單，看這個文檔寫出來之后將來有沒有人會使用咨油，如果有人確實需要這份文檔您炉，那文檔就有存在的價值，比如下面這些：
- 需求背景役电，用戶有什么業(yè)務痛點邻吭，需要什么軟件功能
- 驗收條件，滿足哪些條件可以認為需求驗收通過
- 接口說明宴霸，不同模塊或者組件之間的接口定義
這些文檔有明確的目標受眾，知道自己的文檔是寫給誰看的膏蚓，寫起來就會有明確的針對性瓢谢，哪些地方該細一點，哪些地方可以一筆帶過驮瞧，哪里需要結(jié)合圖表氓扛，這些問題一旦弄清楚，文檔的表意性就能提升一大步论笔。
還有一些內(nèi)容也需要文檔化采郎，比如團隊的 DOD 定義，編碼規(guī)范狂魔，可以幫助團隊設定明確的目標和標準蒜埋，再比如軟件模塊的概要設計說明，可以幫助團隊新進成員快速理解代碼最楷，總之只要我們識別出文檔存在的意義就OK整份。
文檔的形式
文檔應該放在所有人都能方便訪問和同步修改的地方，目前我接觸到比較好的方式是wiki籽孙，訪問修改都很方便烈评，能方便的進行comment并追蹤wiki修改的歷史記錄，有的還能支持markingdown犯建。
像word/pdf格式的文檔讲冠，是直接保存在電腦硬盤上的，為了同步修改一般還需要放在 svn 上适瓦，不管是讀還是寫相對于wiki方式都困難的多竿开。如果你所在的組織還要求對文檔的讀寫進行權(quán)限控制谱仪，那基本上就沒有幾個人愿意看了。
