10 個項目文檔最佳實踐

　　英文原文：10 Software Documentation Best Practices

　　在軟件開發和維護過程中，文檔是必不可少的資料，它可以提高軟件開發的效率，保證軟件的質量，而且在軟件的使用過程中有指導、幫助、解惑的作用。尤其在維護工作中，文檔的重要性更是不言而喻。

　　本文整理了軟件開發中 10 個最佳的文檔編寫實踐，希望能對你的工作有所幫助。

　　1.   將編寫文檔作為開發工作中的一個重要環節（例如，占用總開發時間的 10%）。在軟件開發中，不能沒有文檔，但如果編寫文檔占用了大部分的時間也不合適。可以根據需要制定代碼文檔、需求說明文檔、設計文檔、測試文檔、用戶手冊等，在制定完成后，可以通過版本控制工具或基于 Web 的平臺來管理和共享這些文檔。

　　2.   代碼文檔非常重要的。最好的方式是編寫“自說明”的代碼，變量、方法、類、包等名稱必須是有意義的，代碼流必須是清晰的。對于非常復雜的代碼段，可以包含簡短的注釋行。還可以在代碼中添加相關的標簽或注釋，自動生成 Javadoc 文檔。

　　3.   對于將來接手的開發者，可以為他們準備一些簡短、實用的設計文檔，其中需要包含關鍵設計特性和 UML 圖等，無需出現大量不必要的信息。

　　4.   需求/問題/未交付項目/功能點跟蹤文檔也相當重要。使用跟蹤工具將會使這項工作更加有效率，這些工具可以幫助你完成一些像快速搜索、編輯等方面工作，并可以生成純文本文檔。

　　5.   測試跟蹤文檔也很重要。可以使用一些工具來記錄測試場景和測試結果，并附上一些相關的需求。這樣，可以很容易地監視軟件的功能狀態。

　　6.   文檔是一個持續性的工作，開發人員應該隨時更新或重新生成這些文檔的最新版本，直到開發進程結束。如果一個文檔不是最新的，那么它毫無價值。

　　7.   對于文本形式的文檔，版本相當重要。每一個新的文檔，必須有一個新的版本號（版本號由公司的版本管理策略來定），還需要將這些信息記錄在版本跟蹤表中，以便更好地跟蹤。

　　8.   有一個統一的文檔模板。文檔的頁眉、頁腳、標題、字體大小必須一致，這樣可以增強可讀性。還可以做得更好，比如加上封面、目錄、圖表、詞匯表等。

　　9.   還需要注意文檔格式、使用的語言、錯別字等。輸入錯誤、不一致的表格大小、縮進等問題，可能會分散閱讀者的注意力。

　　10.   將項目中學到的經驗記錄下來，并分享給其他人。開發者在每個項目中都可能會得到一些實用的經驗（比如架構、代碼、配置等），而這些經驗信息不會出現在標準的開發文檔中。開發者要不斷積累并分享這些經驗，這可能會加快當前的開發進度，而且對于將來做一些有挑戰的工作或者重復性的工作，會有很大的幫助。