軟件開發(fā)文檔編制的質量要求

申請免費試用、咨詢電話：400-8352-114

為了使軟件文檔能起到前節(jié)所提到的多種橋梁作用，使它有助于程序員編制程序，有助于管理人員監(jiān)督和管理軟件開發(fā)，有助于用戶了解軟件的工作和應做的操作，有助于維護人員進行有效 的修改和擴充，文檔的編制必須保證一定的質量。質量差的軟件文檔不僅使讀者難于理解，給使用者造成許多不便，而且會削弱對 軟件的管理(管理人員難以確認和評價開發(fā)工作的進展)，增高軟件的成本(一些工作可能被迫返工)，甚至造成更加有害的后果 (如誤操作等)。  

　　造成軟件文檔質量不高的原因可能是： 

　　· 缺乏實踐經(jīng)驗，缺乏評價文檔質量的標準。  

　　· 不重視文檔編寫工作或是對文檔編寫工作的安排不恰當。  

　　最常見到的情況是，軟件開發(fā)過程中不能按給出的進度， 分階段及時完成文檔的編制工作，而是在開發(fā)工作接近完成時集中人力和時間專門編寫文檔。另一方面，和程序工作相比，許多 人對編制文檔不感興趣。于是在程序工作完成以后，不得不應付一下，把要求提供的文檔趕寫出來。這樣的做法不可能得到高質量的文檔。實際上，要得到真正高質量的文檔并不容易，除去應在認識上對文檔工作給予足夠的重視外，常常需要經(jīng)過編寫初稿，聽取意見進行修改，甚至要經(jīng)過重新改寫的過程。 

　　高質量的文檔應當體現(xiàn)在以下一些方面： 

　　①針對性  

　　文檔編制以前應分清讀者對象，按不同的類型、不同層次的讀者，決定怎樣適應他們的需要。例如，管理文檔主要是面 向管理人員的，用戶文檔主要是面向用戶的，這兩類文檔不應像開發(fā) 文檔(面向軟件開發(fā)人員)那樣過多地使用軟件的專業(yè)術語。 

　　②精確性  

　　文檔的行文應當十分確切，不能出現(xiàn)多義性的描 述。同一課題若干文檔內容應該協(xié)調一致，應是沒矛盾的。 

　　③清晰性  

　　文檔編寫應力求簡明，如有可能，配以適當?shù)膱D 表，以增強其清晰性。 

　?、芡暾?nbsp; 

　　任何一個文檔都應當是完整的、獨立的，它應自成體系 。例如，前言部分應作一般性介紹，正文給出中心內容 ，必要時還有附錄，列出參考資料等。同一課題的幾個文檔之間可能 有些部分相同，這些重復是必要的。例如，同一項目的用戶手冊和操 作 
冊中關于本項目功能、性能、實現(xiàn)環(huán)境等方面的描述是沒有差別 的。特別要避免在文檔中出現(xiàn)轉引其它文檔內容的情況。比如，一 
些段落并未具體描述，而用"見××文檔××節(jié)"的方式，這將給 讀者帶來許多不便。 

　　⑤靈活性  

　　各個不同的軟件項目，其規(guī)模和復雜程度有著許 多實際差別，不能一律看待。圖6所列文檔是針對中等規(guī)模的軟件而言的。對于較小的或比較簡單的項目，可做適當調整或合 并。比如，可將用戶手冊和操作手冊合并成用戶操作手冊；軟件需求說明書可包括對數(shù)據(jù)的要求，從而去掉數(shù)據(jù)要求說明書；概要設 計說明書與詳細設計說明書合并成軟件設計說明書等。 

　?、蘅勺匪菪?nbsp; 

　　由于各開發(fā)階段編制的文檔與各階段完成的工作有著緊密的關系，前后兩個階段生成的文檔，隨著開發(fā)工作的逐步 擴展，具有一定的繼承關系。在一個項目各開發(fā)階段之間提供文檔 必定存在著可追溯的關系。例如，某一項軟件需求，必定在設計說明 書，測試計劃以至用戶手冊中有所體現(xiàn)。必要時應能做到跟蹤追查。