現(xiàn)在，很多人認(rèn)為寫(xiě)文檔是一件苦差使，特別是研發(fā)人員，覺(jué)得寫(xiě)文檔是一種浪費(fèi)，和產(chǎn)品開(kāi)發(fā)工作沒(méi)有太大關(guān)系，更愿意把寫(xiě)文檔的時(shí)間用來(lái)寫(xiě)代碼畫(huà)圖紙。
實(shí)際上，一個(gè)成功完整的產(chǎn)品開(kāi)發(fā)項(xiàng)目，最終產(chǎn)出的不只是可交付的實(shí)際產(chǎn)品，還包括產(chǎn)品開(kāi)發(fā)過(guò)程中的文檔，以及產(chǎn)品開(kāi)發(fā)的數(shù)據(jù)。文檔在產(chǎn)品開(kāi)發(fā)項(xiàng)目管理中非常重要，不只是產(chǎn)品的一個(gè)組成部分，而且還是產(chǎn)品開(kāi)發(fā)項(xiàng)目的一種非常重要的管理工具。
文檔是產(chǎn)品的重要組成部分，同時(shí)能得到很好的復(fù)用。一位著名的軟件工程專家曾說(shuō)過(guò)：只要提供完整的架構(gòu)、需求與設(shè)計(jì)文檔，在沒(méi)有源代碼的情況下，可以重新開(kāi)發(fā)出一款與原來(lái)一樣的產(chǎn)品。這段話非常有代表性，道出了文檔的真正作用，因?yàn)檫@些文檔是產(chǎn)品最系統(tǒng)最全面的反映，并且不依賴于具體的實(shí)現(xiàn)方式，哪怕這些文檔針對(duì)的產(chǎn)品不復(fù)存在也能根據(jù)這些文檔開(kāi)發(fā)出同樣的產(chǎn)品。再比如，很多開(kāi)源項(xiàng)目的源代碼和可運(yùn)行的產(chǎn)品是免費(fèi)的，但相關(guān)的設(shè)計(jì)文檔和使用說(shuō)明文檔確實(shí)收費(fèi)的，文檔的重要性由此可見(jiàn)一斑。
文檔是管理者跟蹤和控制項(xiàng)目的一個(gè)重要工具。管理都跟蹤和控制項(xiàng)目主要通過(guò)面對(duì)面的交流與文檔兩種方式，交流具有隨機(jī)性、即時(shí)性與局限性的特點(diǎn)，而文檔具有延續(xù)性、長(zhǎng)期性與全面性的特點(diǎn)，特別是報(bào)告與進(jìn)度文檔能讓管理者對(duì)項(xiàng)目的整體情況了如指掌。
文檔在產(chǎn)品開(kāi)發(fā)項(xiàng)目各角色之間起多種橋梁作用。研發(fā)人員在各個(gè)階段中以文檔作為前階段工作成果的體現(xiàn)和后階段工作的依據(jù)，這個(gè)作用是顯而易見(jiàn)的。研發(fā)過(guò)程中研發(fā)人員需制定 一些工作計(jì)劃或工作報(bào)告，這些計(jì)劃和報(bào)告都要提供給管理人員，并得到必要的支持。管理人員則可通過(guò)這些文檔了解項(xiàng)目安排、進(jìn)度、資源使用和成果等。研發(fā)人員需為用戶了解系統(tǒng)的使用、操作和維護(hù)提供詳細(xì)的資料即用戶文檔。
也許有人會(huì)說(shuō)，編寫(xiě)和維護(hù)文檔需要花費(fèi)大量的時(shí)間和精力，并要配備相應(yīng)的管理人員，這必然會(huì)增加公司的運(yùn)營(yíng)成本，從短期和單個(gè)項(xiàng)目來(lái)說(shuō)確實(shí)是這樣，但從長(zhǎng)遠(yuǎn)和一系列項(xiàng)目來(lái)看，其會(huì)帶來(lái)降低成本、提高質(zhì)量、提高項(xiàng)目管理水平、提高用戶滿意度等好處。因?yàn)橐粋€(gè)項(xiàng)目中完整的流程、規(guī)范和經(jīng)驗(yàn)可以很容易的復(fù)制到另一個(gè)新項(xiàng)目中，這其中就是有文檔把項(xiàng)目的整個(gè)過(guò)程記錄在案，而不是在人的腦袋里，這樣就能在另一個(gè)項(xiàng)目中得到很好的復(fù)用。
寫(xiě)文檔的本質(zhì)是設(shè)計(jì)出問(wèn)題的解決方案和規(guī)范項(xiàng)目管理。設(shè)計(jì)和直接寫(xiě)代碼的區(qū)別是設(shè)計(jì)需要站在一個(gè)比寫(xiě)代碼更高的層次上來(lái)看問(wèn)題，當(dāng)面對(duì)一個(gè)問(wèn)題時(shí)，很可能另外的問(wèn)題與之相關(guān)聯(lián)(隱式地/顯式地)，此時(shí)如果寫(xiě)分析設(shè)計(jì)文檔，那么相當(dāng)于充分全面地考慮這個(gè)問(wèn)題，而直接寫(xiě)代碼往往會(huì)讓人沉溺于細(xì)節(jié)。由此可見(jiàn)編寫(xiě)必要的文檔會(huì)使自己考慮問(wèn)題更全面、更系統(tǒng)，是一種很好的習(xí)慣。
評(píng)審與修改文檔比評(píng)審與修改具體的實(shí)現(xiàn)容易、簡(jiǎn)單。在進(jìn)行系統(tǒng)的相關(guān)評(píng)審時(shí)，看一份架構(gòu)文檔或系統(tǒng)設(shè)計(jì)文檔就能對(duì)系統(tǒng)的結(jié)構(gòu)、系統(tǒng)的組成及系統(tǒng)的實(shí)現(xiàn)思路有一個(gè)全面的了解與認(rèn)識(shí)，評(píng)審這樣的文檔則比想通過(guò)代碼獲得這些信息容易簡(jiǎn)單多了。從感情的角度來(lái)說(shuō)，每一個(gè)開(kāi)發(fā)工程師都對(duì)自己的代碼有一種依戀感，害怕丟棄已有的代碼和方案;而修改文檔則會(huì)讓這種感覺(jué)變得非常小。
談了這么多，系統(tǒng)開(kāi)發(fā)工程師肯定會(huì)振振有詞的說(shuō)：我覺(jué)得用代碼來(lái)表達(dá)解決問(wèn)題的方案比寫(xiě)文檔更加方便和直接。就單個(gè)問(wèn)題在很短的時(shí)間而言，這是一個(gè)站的住腳的理由——代碼的字?jǐn)?shù)肯定比文檔的敘述要少得多，而且多數(shù)開(kāi)發(fā)工程師的思維更加適應(yīng)編程語(yǔ)言。但是如果涉及到多個(gè)問(wèn)題或者幾個(gè)系統(tǒng)模塊，時(shí)間跨度是幾個(gè)版本的時(shí)候，上面的理由多少顯得有些蒼白無(wú)力。
誠(chéng)然，文檔不是越多越好，要恰到好處。寫(xiě)一些質(zhì)量差、脫離實(shí)際的文檔，只會(huì)適得其反，寫(xiě)文檔的人浪費(fèi)了大量的時(shí)間和