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

申請(qǐng)免費(fèi)試用、咨詢(xún)電話：400-8352-114

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

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

　　· 缺乏實(shí)踐經(jīng)驗(yàn)，缺乏評(píng)價(jià)文檔質(zhì)量的標(biāo)準(zhǔn)。  

　　· 不重視文檔編寫(xiě)工作或是對(duì)文檔編寫(xiě)工作的安排不恰當(dāng)。  

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

　　高質(zhì)量的文檔應(yīng)當(dāng)體現(xiàn)在以下一些方面： 

　?、籴槍?duì)性  

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

　?、诰_性  

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

　?、矍逦?nbsp; 

　　文檔編寫(xiě)應(yīng)力求簡(jiǎn)明，如有可能，配以適當(dāng)?shù)膱D 表，以增強(qiáng)其清晰性。 

　?、芡暾?nbsp; 

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

　?、蒽`活性  

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

　?、蘅勺匪菪?nbsp; 

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