優秀軟件文檔的必備要素

在項目開發完成了三分之二的時候，風險承擔人對一個正在設計的特性提出疑問，提出了這樣的問題：為什么你花了400小時的時間構建一個全自動的銷售點應用程序？我們只需要一個電子數據表來提交我們的銷售信息。

    當你拼命地試圖回憶當初的需求會議的時候，你的反應只能是可憐說當初在項目開始階段團隊理解出現了問題。

    當然，這是一個很極端的例子，但是卻是在項目開發中經常出現。你可以將這個問題歸結到需求管理之上。我將這個過程描述為一個包含五個階段的反復過程，其目標是在項目的生命周期中管理項目開發的捕獲、文檔、跟蹤和交付。下面是這五個階段的一個簡單描述：

    第一階段：初始化

    這個階段從項目請求開始，到項目被核準結束。這個階段的目標是確定項目是否值得開發，與別的項目相比其優先級別如何。其步驟包括：

    初始項目請求。

    IT區域回顧。

    概要成本估算，CBA，或者預計的ROI。

    第二階段：確定或啟發

    這個步驟是指詳細需求的組織化的和結構化。它包括：

    最初的項目請求的回顧。

    項目風險承擔人的初步確定。

    啟發計劃的完成。
 
    反復地執行需求啟發步驟，包括會見、交流或其它技術。

    初步需求列表。

    商業規則的確定。

    文檔，包括使用案例、上下文圖表及其它更多內容。

    功能和非功能需求的正式創建。

    和大多數同行一樣，我明白軟件文檔的重要性。不幸的是，在任務開始前我很少閱讀文檔。相反，我常常像視線不清的父母一樣，在裝配好他們孩子的自行車之后，還落下一兩個零部件沒裝上。

    如果我們明白文檔的重要性，那為什么我們不更經常用它呢？然而，許多軟件文檔存在以下問題：

    •錯誤的語法和/或拼錯的詞語

    •不完整

    •過時或不準確

    •過于冗長

    •未經解釋的縮略語或專用術語

    •查找信息困難

    存在這些問題的主要原因是軟件文檔常常被退居次位。工程預算迫使我們優先考慮開發過程中的主要活動，也就是那些可以看得到利潤的地方。編寫文檔需要成本，因而它常常成為一項主觀上的活動，而且通常被認為沒有重要作用，應該盡量避免。許多項目經理認為客戶不需要文檔，它只是用來裝點門面的。

    軟件文檔質量差的另外一個原因在于文檔撰寫者。許多應用程序開發經理認為軟件文檔的編寫是軟件開發過程的一個標準組成部分，因此要求開發人員在編碼的過程中產出文檔。

    盡管這種做法在理論上行得通，但它沒有考慮開發人員編寫文檔的能力。簡單來說，技術人員是用來開發軟件而不是編寫文檔的。為了解決這個問題，許多應用程序開發經理雇傭專業技術文檔編寫者或業務分析師，以期改進軟件文檔的質量。但這又遇到了另一個難題：專業編寫者及業務分析師的技術水平有限。

    解決這個問題要考慮需要編寫的文檔以及文檔的預期讀者。一般的規則是，寫文檔需要團隊協作，這樣就允許開發人員和文檔編寫者利用彼此的長處，取長補短。例如，如果預期讀者是系統設計師，開發人員需要提供技術細節，然后文檔編寫者按照正確語法組織和編輯內容。

    不考慮預期讀者或專門編寫者，軟件文檔的質量取決于其可用性，可從以下6個方面去評價其可用性：

    •應用性：文檔是否提供相關信息？

    •及時性：信息是否及時？

    •準確性：信息是否正確？

    •完整性：文檔是否足夠詳細而又不會太過拘泥細節？

    •可得性：文檔是否隨時可得？

    •可用性：你能否很快憑直覺就找到所需信息？

    軟件文檔的最主要目標是傳達一個系統的技術要素和使用方法。第二個目標是提供軟件開發過程中的需求，決策，行為，角色和責任的書面記錄。只有實現了這兩個目標，軟件文檔才真正提供了有意義的信息。

原文轉自：http://www.anti-gravitydesign.com