像很多同行一樣，我理解軟件文檔的價值。不幸的是，在開始一項任務之前我卻很少閱讀軟件文檔。相反，我通常會模仿目光短淺的父母，他們在組裝好孩子的自行車時，總會多出一些零件來。
如果我們知道軟件文檔的價值，那么為什么不經常使用它呢？對于新手，大多數軟件文檔都存在很多下面提到的這些問題：
• 糟糕的語法和/或拼寫錯誤的詞語
• 不完整
• 過期或不準確
• 篇幅太長
• 首字母縮寫沒有解釋或術語不專業
• 難于找到信息或在文檔中定位
存在這些問題的主要原因是軟件文檔通常沒有被給予足夠的重視。項目預算被迫將主要活動花在了開發工作上，在那里管理層很容易看到他們的收益。值得投入成本的文檔工作通常都是主觀的，而且通常被刻畫為需要避免的成本，因為它們被認為不能產生投資回報（ROI）。很多項目經理將客戶所需要的最少文檔看作是“鍍金”。
軟件文檔的另外一個麻煩來源是文檔的作者。很多應用程序開發經理覺得軟件文檔是開發工作的一個標準部分，因此，要求他們的開發人員在編碼時也編寫軟件文檔。
雖然這在理論上是說得過去的，但是不應該將開發人員看成文檔作者。很簡單，技術人員只被培訓如何開發，而沒有被培訓如何寫文檔。為了解決這一問題，很多應用程序開發經理嘗試通過聘請一些技術性寫手或商業分析人員來提高他們的軟件文檔的質量。這就導致出現了一個相反的問題：技術寫手和商業分析人員通常只有有限的技術技能。
解決方案依賴于文檔，文檔應該迎合其潛在讀者的口味。這方面的通用規則是要求使用一個協同工作方法來編寫文檔，這種方法允許開發人員和寫手發揮他們的長處。例如，如果潛在的讀者是系統設計人員，那么開發人員應該提供詳細的輸入，但是允許技術寫手去組織和編輯內容以使文檔符合語法。
不管潛在的讀者還是被選中的讀者，軟件文檔的質量與其可使用性相關，以下六個屬性可以用來測量軟件文檔的可使用性：
• 適用性：文檔提供了相關的信息嗎？
• 合時性：文檔所提供的是當時的信息嗎？
• 正確性：文檔所提供的信息正確嗎？
• 完整性：文檔是不是足夠詳細？
• 可用性：文檔隨手可用嗎？
• 可使用性：能夠快速直觀地找到所需的信息嗎？
軟件文檔的首要目標是表達系統的技術元素和用法。軟件文檔的次要目標是提供一項開發工作的需求、決策、動作、角色和責任的書面記錄。只有在你意識到這兩個目標時，你的文檔才能提供有意義的信息
