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