最好的Web開(kāi)發(fā)人員總是可以寫(xiě)出帶有好注釋的漂亮代碼，但是，他們一般也不會(huì )編寫(xiě)專(zhuān)門(mén)給非開(kāi)發(fā)人員閱讀的文檔。最好的工程師愿意瘋狂地開(kāi)發(fā)應用程序，但是不愿意花一點(diǎn)時(shí)間去編寫(xiě)文檔或向其他人說(shuō)明應用程序。他們認為，代碼就是文檔，而且有技術(shù)的人都能夠理解代碼，所以編寫(xiě)額外的文檔是在浪費時(shí)間。
 
然而，現實(shí)情況是，并非所有人都能夠讀懂API或配置管理清單。業(yè)務(wù)用戶(hù)、項目經(jīng)理及其他非技術(shù)人員經(jīng)常需要了解應用程序的內部工作方式，這樣他們才能更好地完成自己的工作，而技術(shù)文檔并不能滿(mǎn)足他們的需求。這些輔助人員是T組織正常運行的重要條件，如果沒(méi)有這些信息，他們就會(huì )感到被疏遠，不知道該如何與開(kāi)發(fā)和運維團隊交流，或者也不知道如何將他們的工作傳達給業(yè)務(wù)部門(mén)、項目管理部門(mén)或其他非技術(shù)部門(mén)。


 
此外，還有一種借口:由于軟件開(kāi)發(fā)速度越來(lái)越快，所以開(kāi)發(fā)人員和運維人員需要進(jìn)一步提高生產(chǎn)力，減少交叉培訓、編寫(xiě)文檔和內部培訓的時(shí)間。這同樣也是不對的。如果沒(méi)有文檔，我們就無(wú)法將遺留系統引入組織中。遺留系統通常是每隔幾年就需要更新一次，因為知道如何維護這些系統的人可能已經(jīng)離開(kāi)公司，或者根本不記得如何維護這些系統，也沒(méi)有參考資料可以查閱。
 
解決方法:將文檔加到成功條件中，共同分擔文檔編寫(xiě)責任
 
大多數基于Web的組織都會(huì )使用一種敏捷或精益方法來(lái)開(kāi)發(fā)軟件，而且這個(gè)過(guò)程通常需要定期極查已完成的上作和核對任務(wù)執行情況，從而落實(shí)項目的進(jìn)展情況。這樣的話(huà)，文檔就可以整合到開(kāi)發(fā)與運維團隊的文化中，而且組織也能夠從中獲益，例如產(chǎn)出質(zhì)量更好的代碼和發(fā)現設計問(wèn)題等。
 
這個(gè)過(guò)程需要管理層的參與才能取得成功。如果管理層只關(guān)注于完成進(jìn)度，而不注意形成文檔編寫(xiě)文化，那么這種過(guò)程是不可能成功的。只是認同文檔屬于軟件開(kāi)發(fā)生命周期的一部分，但不使用必要的文檔工具，也不投入時(shí)間，那么形成文檔編寫(xiě)文化的目標就不可能實(shí)現。
 
而且，開(kāi)發(fā)與運維團隊都必須參與到文檔編寫(xiě)文化的創(chuàng )建過(guò)程中，他們必須共同協(xié)作，而不能各自為政。在一些超大型組織中，最好配備一位有開(kāi)發(fā)或運維背景的全職技術(shù)文檔工程師。因為這個(gè)人有技術(shù)背景，從而也就不容易讓人懷疑他的專(zhuān)業(yè)性。
 
好處:培養責任意識
 
配備一位有技術(shù)背景的文檔編寫(xiě)人員(技術(shù)文檔工程師)有利于鼓勵開(kāi)發(fā)與運維團隊主動(dòng)承擔起編寫(xiě)代碼文檔、應用文檔和流程文檔的責任。一位經(jīng)驗豐富的技術(shù)文檔工程師可以指導他人編寫(xiě)出有效的文檔，或者幫助他們養成編寫(xiě)文檔的習慣。這樣可以幫助反對編寫(xiě)文檔的工程師開(kāi)始接受文檔編寫(xiě)工作。
 
一旦每位網(wǎng)站制作工程師都愿意編寫(xiě)自己的文檔，那么技術(shù)文檔工程師就可以將角色從布道師和寫(xiě)手，轉變?yōu)榫庉嫼椭笇д?，?zhuān)職負責保證文檔的正確組織和發(fā)布，以及幫助工程師改進(jìn)技術(shù)文檔的質(zhì)量。當然，不同部門(mén)的技術(shù)文檔工程師有不同的職責，這取決于Web業(yè)務(wù)的組織方式，但是作為文檔編寫(xiě)的關(guān)鍵人物，他可以保證文檔真正編寫(xiě)完成。