和大多數(shù)同行一樣，我明白軟件文檔的重要性。不幸的是，在任務(wù)開始前我很少閱讀文檔。相反，我常常像視線不清的父母一樣，在裝配好他們孩子的自行車之后，還落下一兩個(gè)零部件沒裝上。 如果我們明白文檔的重要性，那為什么我們不更經(jīng)常用它呢？然而，許多軟件文檔存在以下問題：
· 錯(cuò)誤的語法和/或拼錯(cuò)的詞語
· 不完整
· 過時(shí)或不準(zhǔn)確
· 過于冗長
· 未經(jīng)解釋的縮略語或?qū)Ｓ眯g(shù)語
· 查找信息困難
存在這些問題的主要原因是軟件文檔常常被退居次位。工程預(yù)算迫使我們優(yōu)先考慮開發(fā)過程中的主要活動(dòng)，也是那些可以看得到利潤的地方。編寫文檔需要成本，因而它常常成為一項(xiàng)主觀上的活動(dòng)，而且通常被認(rèn)為沒有重要作用，應(yīng)該盡量避免。許多項(xiàng)目經(jīng)理認(rèn)為客戶不需要文檔，它只是用來裝點(diǎn)門面的。
軟件文檔質(zhì)量差的另外一個(gè)原因在于文檔撰寫者。許多應(yīng)用程序開發(fā)經(jīng)理認(rèn)為軟件文檔的編寫是軟件開發(fā)過程的一個(gè)標(biāo)準(zhǔn)組成部分，因此要求開發(fā)人員在編碼的過程中產(chǎn)出文檔。
盡管這種做法在理論上行得通，但它沒有考慮開發(fā)人員編寫文檔的能力。簡單來說，技術(shù)人員是用來開發(fā)軟件而不是編寫文檔的。為了解決這個(gè)問題，許多應(yīng)用程序開發(fā)經(jīng)理雇傭?qū)I(yè)技術(shù)文檔編寫者或業(yè)務(wù)分析師，以期改進(jìn)軟件文檔的質(zhì)量。但這又遇到了另一個(gè)難題：專業(yè)編寫者及業(yè)務(wù)分析師的技術(shù)水平有限。
解決這個(gè)問題要考慮需要編寫的文檔以及文檔的預(yù)期讀者。一般的規(guī)則是，寫文檔需要團(tuán)隊(duì)協(xié)作，這樣允許開發(fā)人員和文檔編寫者利用彼此的長處，取長補(bǔ)短。例如，如果預(yù)期讀者是系統(tǒng)設(shè)計(jì)師，開發(fā)人員需要提供技術(shù)細(xì)節(jié)，然后文檔編寫者按照正確語法組織和編輯內(nèi)容。不考慮預(yù)期讀者或?qū)ｉT編寫者，軟件文檔的質(zhì)量取決于其可用性，可從以下6個(gè)方面去評價(jià)其可用性：
· 應(yīng)用性：文檔是否提供相關(guān)信息？
· 及時(shí)性：信息是否及時(shí)？
· 準(zhǔn)確性：信息是否正確？
· 完整性：文檔是否足夠詳細(xì)而又不會(huì)太過拘泥細(xì)節(jié)？
· 可得性：文檔是否隨時(shí)可得？
· 可用性：你能否很快憑直覺找到所需信息？
軟件文檔的主要目標(biāo)是傳達(dá)一個(gè)系統(tǒng)的技術(shù)要素和使用方法。第二個(gè)目標(biāo)是提供軟件開發(fā)過程中的需求，決策，行為，角色和責(zé)任的書面記錄。只有實(shí)現(xiàn)了這兩個(gè)目標(biāo)，軟件文檔才真正提供了有意義的信息。
