10 個項目文檔最佳實務

來源:互聯網
上載者:User

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

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

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

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

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

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

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

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

7.  對於文本形式的文檔,版本相當重要。每一個新的文檔,必須有一個新的版本號碼(版本號碼由公司的版本管理原則來定),還需要將這些資訊記錄在版本跟蹤表中,以便更好地跟蹤。 

8.  有一個統一的文件範本。文檔的頁首、頁尾、標題、字型大小必須一致,這樣可以增強可讀性。還可以做得更好,比如加上封面、目錄、圖表、詞彙表等。 

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

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

英文原文:10 Software Documentation Best Practices



相關文章

Beyond APAC's No.1 Cloud

19.6% IaaS Market Share in Asia Pacific - Gartner IT Service report, 2018

Learn more >

Apsara Conference 2019

The Rise of Data Intelligence, September 25th - 27th, Hangzhou, China

Learn more >

Alibaba Cloud Free Trial

Learn and experience the power of Alibaba Cloud with a free trial worth $300-1200 USD

Learn more >

聯繫我們

該頁面正文內容均來源於網絡整理,並不代表阿里雲官方的觀點,該頁面所提到的產品和服務也與阿里云無關,如果該頁面內容對您造成了困擾,歡迎寫郵件給我們,收到郵件我們將在5個工作日內處理。

如果您發現本社區中有涉嫌抄襲的內容,歡迎發送郵件至: info-contact@alibabacloud.com 進行舉報並提供相關證據,工作人員會在 5 個工作天內聯絡您,一經查實,本站將立刻刪除涉嫌侵權內容。