系統(tǒng)開發(fā)的文檔管理

ftonny

因?yàn)槟壳皡⑴c一個(gè)系統(tǒng)的開發(fā)管理工作，希望多了解一些有關(guān)的知識(shí)�，F(xiàn)在遇到的一個(gè)最大的問題就是開發(fā)文檔的管理，好像每個(gè)程序員都不是很愿意做文檔，應(yīng)此在版本控制方面就存在問題，不知道各位有什么好的建議？

jinzhi

最初由 ftonny 發(fā)布\r\n[B]因?yàn)槟壳皡⑴c一個(gè)系統(tǒng)的開發(fā)管理工作，希望多了解一些有關(guān)的知識(shí)�，F(xiàn)在遇到的一個(gè)最大的問題就是開發(fā)文檔的管理，好像每個(gè)程序員都不是很愿意做文檔，應(yīng)此在版本控制方面就存在問題，不知道各位有什么好的建議？ [/B]

\r\n\r\n文檔和程序編制應(yīng)該分開，程序人員應(yīng)該按照文檔要求來編制程序，而不應(yīng)有其自主決定該如何開發(fā)，我覺得國內(nèi)許多小項(xiàng)目的開發(fā)都是在程序員有一個(gè)基本的了解后就開始開發(fā)程序，然后在開發(fā)過程中不斷改進(jìn)，因此導(dǎo)致文檔的建立存在問題。你作為管理人員我認(rèn)為應(yīng)該先確定系統(tǒng)分析人員，并要求系統(tǒng)分析人員提供完整的文檔，在文檔完成后再要求程序人員進(jìn)行編制。不過實(shí)現(xiàn)起來比較困難，大家覺得是不是這樣？

ftonny

我明白是要把文檔和編程分開，而且應(yīng)該在編程之前做好文檔，按文檔要求Coding，但是如果在Coding的過程中有變化，是要用什么好辦法去控制文檔和實(shí)際程序的Match，或者說是版本的統(tǒng)一呢？謝謝。

jinzhi

最初由 ftonny 發(fā)布\r\n[B]我明白是要把文檔和編程分開，而且應(yīng)該在編程之前做好文檔，按文檔要求Coding，但是如果在Coding的過程中有變化，是要用什么好辦法去控制文檔和實(shí)際程序的Match，或者說是版本的統(tǒng)一呢？謝謝。 [/B]

\r\n這時(shí)說明一個(gè)問題，你的系統(tǒng)分析做得不夠深入，或者沒有得到用戶的最后確認(rèn)，當(dāng)然這種問題肯定會(huì)存在，我覺得這時(shí)你應(yīng)該制定一個(gè)流程，而不是要求程序員去修改分析文檔，用戶或者編程人員認(rèn)為需要更改設(shè)計(jì)的，必須通過系統(tǒng)分析員，由系統(tǒng)分析員下達(dá)最后的確認(rèn)修改設(shè)計(jì)，并提供相應(yīng)的文檔，否則編程人員無權(quán)更改設(shè)計(jì)。

ftonny

樓上說得有道理，總之就是無論任何變動(dòng)，都需要先取得系統(tǒng)分析員的同意，在文檔中作出記錄之后才可以修改程序，是不是這個(gè)意思呢？

cg2001

本來文檔和開發(fā)的人不一定要相同，應(yīng)該各司其職。\r\n你用過Rational的SODA這個(gè)軟件嗎？可以看一下。\r\n\r\n不過中國的程序員不愿意寫東西倒是真的，例如代碼說明等

ftonny

謝謝樓上，其實(shí)我想說的就是這個(gè)問題，我們的程序員都是絕頂聰明的，可是現(xiàn)在卻比不上印度，少的就是管理，我聽說他們?cè)谧x大學(xué)的時(shí)候，如果被淘汰，不是一個(gè)人，而是一個(gè)學(xué)習(xí)小組，好像很殘酷......//thinking

cg2001

中國人缺少的是團(tuán)隊(duì)精神和誠信。\r\n也許是中國人太聰明了，而不喜歡規(guī)范。就像有種說法：“中國人一個(gè)人是條龍，一群人是條蟲”；足球也罷，程序員也罷，都是如此。

ftonny

好了，不扯遠(yuǎn)了，言歸正傳，我找了幾篇有關(guān)文檔管理的文章，供大家參考。\r\n\r\n（一）\r\n文檔的管理和維護(hù) \r\n\r\n　　在整個(gè)軟件生存期中，各種文檔作為半成品或是最終成品， 會(huì)不斷地生成、修改或補(bǔ)充。為了最終得到高質(zhì)量的產(chǎn)品，達(dá)到上 節(jié)提出的質(zhì)量要求，必須加強(qiáng)對(duì)文檔的管理。以下幾個(gè)方面是應(yīng)注意做到的： \r\n\r\n\r\n　�、佘浖�開發(fā)小組應(yīng)設(shè)一位文檔保管人員，負(fù)責(zé)集中保管本 項(xiàng)目已有文檔的兩套主文本。兩套文本內(nèi)容完全一致。其中的一套可按一定手續(xù)，辦理借閱。 \r\n\r\n\r\n　�、谲浖�開發(fā)小組的成員可根據(jù)工作需要在自己手中保存一些個(gè)人文檔。這些一般都應(yīng)是主文本的復(fù)制件，并注意和主文本保持一致，在作必要的修改時(shí)，也應(yīng)先修改主文本。 \r\n\r\n\r\n　�、坶_發(fā)人員個(gè)人只保存著主文本中與他工作相關(guān)的部分文檔。 \r\n\r\n\r\n　�、茉谛挛臋n取代了舊文檔時(shí)，管理人員應(yīng)及時(shí)注銷舊文檔。 在文檔內(nèi)容有更動(dòng)時(shí)，管理人員應(yīng)隨時(shí)修訂主文本，使其及時(shí)反映更新了的內(nèi)容。 \r\n\r\n\r\n　�、蓓�(xiàng)目開發(fā)結(jié)束時(shí)，文檔管理人員應(yīng)收回開發(fā)人員的個(gè)人文檔。發(fā)現(xiàn)個(gè)人文檔與主文本有差別時(shí)，應(yīng)立即著手解決。這常常是未及時(shí)修訂主文本造成的。 \r\n\r\n\r\n　　⑥在軟件開發(fā)過程中，可能發(fā)現(xiàn)需要修改已完成的文檔，特別是規(guī)模較大的項(xiàng)目，主文本的修改必須特別謹(jǐn)慎。修改以前要充分估計(jì)修改可能帶來的影響，并且要按照：提議、評(píng)議、審核、批準(zhǔn)和實(shí)施等步驟加以嚴(yán)格的控制。\r\n\r\n(To be continued)

ftonny

（二）\r\n\r\n如何編寫高質(zhì)量“軟件需求說明書”（上）\r\n\r\n原著：Karl E Wieger，Process Impact \r\n\r\n　　你的工程應(yīng)該有個(gè)好的起點(diǎn)。一個(gè)小組要帶領(lǐng)客戶進(jìn)入需求啟發(fā)階段而且你要寫軟件需求說明書。這份說明有些大，但客戶會(huì)很重視，所以說明必須得到贊同。\r\n\r\n\r\n　　現(xiàn)在你正在設(shè)計(jì)其中的一個(gè)特性，已經(jīng)發(fā)現(xiàn)了需求的一些問題。你可以用多種不同的方式解釋需求15；需求9 的說明正好與需求21相反，你因該相信哪一個(gè)？需求24非常含糊，你根本不明白它的意思；你不得不花上一個(gè)小時(shí)與2位開發(fā)人員討論需求30，只因?yàn)槟銈儗?duì)其各有各的理解；并且，唯一能夠澄清這些問題的客戶沒有給你們答復(fù)。你被迫破解眾多需求的含義，并且你能預(yù)料到，如果你錯(cuò)了，你要做大量的重復(fù)工作。 \r\n\r\n\r\n　　許多軟件需求說明書（SRS）寫得非常糟糕。任何產(chǎn)品的質(zhì)量需要其原始材料的質(zhì)量保證，糟糕的軟件需求說明書不可能產(chǎn)出優(yōu)秀的軟件。不幸的是，幾乎沒有開發(fā)人員受過與需求的抽象、分析、文檔、質(zhì)檢有關(guān)的教育。而且，沒有非常多的好需求可以借鑒學(xué)習(xí)，部分原因是很少有工程可以找到一個(gè)好的借鑒，其他原因是公司不愿意將其產(chǎn)品說明書放在公共區(qū)域。\r\n\r\n\r\n　　這篇文章描述了高質(zhì)量需求敘述和說明的幾個(gè)特性（特點(diǎn)）。我們將用這些觀點(diǎn)檢查一些有缺陷的需求，帶著痛楚重新編寫。而且我會(huì)談一些如何編寫好的需求的提示。你也許想通過這些質(zhì)量標(biāo)準(zhǔn)評(píng)估你的工程需求。對(duì)于修訂，也許遲了，但你會(huì)學(xué)到一些有用的東西，并幫助你的小組在下次編寫出更好的需求。\r\n\r\n\r\n　　不要期望能夠編寫出一份能體現(xiàn)需求應(yīng)具備的所有特性的SRS。無論你怎么細(xì)化、分析、評(píng)論和優(yōu)化需求，都不可能達(dá)到完美。但是，如果你牢記這些特性，你就會(huì)編寫出更好的需求，生產(chǎn)出更好的產(chǎn)品。\r\n\r\n高質(zhì)量需求敘述的特性\r\n\r\n　　我們?nèi)绾螐囊恍┯袉栴}的需求中分辨出好的軟件需求？這一節(jié)將分別介紹需求敘述應(yīng)體現(xiàn)的6個(gè)特性，下一節(jié)將從整體上介紹SRS文檔應(yīng)具備的特性。判斷每個(gè)需求是否具備應(yīng)有的特性的一種方式是由持有不同觀點(diǎn)的工程資金管理人所作的正規(guī)檢查。另一種有力的方法是在編寫代碼前依據(jù)需求編寫測(cè)試?yán)�子。測(cè)試?yán)�子能夠明確顯現(xiàn)在需求中描述的產(chǎn)品行為（特性），能夠顯現(xiàn)缺陷、冗余和含糊之處。 \r\n\r\n\r\n　　正確：每個(gè)需求必須精確描述要交付的功能。正確性依據(jù)于需求的來源，如真實(shí)的客戶或高級(jí)別的系統(tǒng)需求說明書。一個(gè)軟件需求與其對(duì)應(yīng)的系統(tǒng)需求說明書相抵觸是不正確的（當(dāng)然，系統(tǒng)需求說明書本身可能不正確）。\r\n\r\n\r\n　　只有用戶的代表能夠決定用戶需求的正確性，這就是為什么在檢查需求時(shí)，要包括他們或他們的代理的關(guān)鍵所在。不包括用戶的需求檢查就會(huì)導(dǎo)致開發(fā)人員的：“這是沒意義的”，“這可能是他們的意思”等眾所周知的猜測(cè)。 \r\n\r\n\r\n　　可行性：在已知的能力、有限的系統(tǒng)及其環(huán)境中每個(gè)需求必須是可實(shí)現(xiàn)的。為了避免需求的不可行性，在需求分析階段應(yīng)該有一個(gè)開發(fā)人員參與，在抽象階段應(yīng)該有市場(chǎng)人員參與。這個(gè)開發(fā)人員應(yīng)能檢查在技術(shù)上什么能做什么不能做，哪些需要需要額外的付出或者和其他的權(quán)衡。\r\n\r\n\r\n　　必要性：每個(gè)需求應(yīng)載明什么是客戶確實(shí)需要的，什么要順應(yīng)于外部的需求，接口或標(biāo)準(zhǔn)。每個(gè)需求源于你認(rèn)可、具有權(quán)說明需求的原始資料，這是考慮必需的另外情形（譯注，此句翻譯不順，請(qǐng)參照原文：Another way to think of “necessary” is that each requirement originated from a source you recognize as having the authority to specify requirements）。跟蹤每個(gè)需求回溯到出處，如用例，系統(tǒng)需求，規(guī)章，或來自其他用戶的意見。如果你不能標(biāo)識(shí)出處，可能需求只是個(gè)鍍金的例子，沒有真正的必須。\r\n\r\n\r\n　　優(yōu)先權(quán)：為了表明在一個(gè)詳細(xì)的產(chǎn)品版本中應(yīng)包含哪些要點(diǎn)，需要為每個(gè)需求，特征，或用例分配實(shí)現(xiàn)的優(yōu)先權(quán)�？蛻艋蚱浯�理都應(yīng)有強(qiáng)烈的責(zé)任建立優(yōu)先權(quán)。如果所有的需求都被視為同等重要，那么由于在開發(fā)中，預(yù)算削減，計(jì)劃超時(shí)或組員的離開導(dǎo)致新的需求時(shí)， 項(xiàng)目經(jīng)理將不能起到作用。優(yōu)先權(quán)的作用是提供給客戶的價(jià)值，實(shí)現(xiàn)的相關(guān)費(fèi)用，實(shí)現(xiàn)相關(guān)聯(lián)的有關(guān)技術(shù)風(fēng)險(xiǎn)。 \r\n\r\n\r\n　　我是用3種級(jí)別的優(yōu)先權(quán)：高優(yōu)先權(quán)表明需求必須體現(xiàn)在下一個(gè)產(chǎn)品版本中，中優(yōu)先權(quán)表明需求是必須的，但是如果需要可以推遲到晚一些的產(chǎn)品版本中，低優(yōu)先權(quán)表明有它很好，但我們必須認(rèn)識(shí)到如果沒有充足的時(shí)間或資源，它可以被放棄掉。\r\n\r\n\r\n　　明確：需求敘述的讀者應(yīng)只能從其得到唯一的解釋說明，同樣，一個(gè)需求的多個(gè)讀者也應(yīng)達(dá)成共識(shí)。自然語言極易導(dǎo)致含糊。要避免使用一些對(duì)于SRS作者很清楚但對(duì)于讀者不清楚的主觀詞匯，如：用戶友好性，容易，簡(jiǎn)單，快速，有效，幾個(gè)，藝術(shù)級(jí)，改善的，最大，最小等等。每寫一個(gè)需要都應(yīng)簡(jiǎn)潔，簡(jiǎn)單，直觀的采用用戶熟知的語言，不要采用計(jì)算機(jī)術(shù)語。檢查需求模糊的有效方式包括需求說明書的正規(guī)檢查，根據(jù)需求寫測(cè)試，建立用戶的假想來說明產(chǎn)品某個(gè)特定部分預(yù)期的特性。 \r\n\r\n\r\n　　可證實(shí)：看你是否能夠做出測(cè)試計(jì)劃或其他驗(yàn)證方式，如檢查和實(shí)證，來決定在產(chǎn)品中每個(gè)需求是否正確的實(shí)現(xiàn)。如果需求是不可驗(yàn)證的，決定需求是不是正確的實(shí)現(xiàn)就成了判斷的事。需求之間不一致，不可行，不明確也能導(dǎo)致不可證實(shí)。任何需求如果說產(chǎn)品將要支持什么也是不可證實(shí)的。\r\n\r\n高質(zhì)量需求說明的特征\r\n\r\n　　一個(gè)完整的SRS不僅是包括長(zhǎng)長(zhǎng)的功能性需求列表，還包括外部接口描述和一些諸如質(zhì)量屬性，期望性能的非功能性需求。下面描述了高質(zhì)量的SRS的一些特性。\r\n\r\n\r\n　　完整：不應(yīng)該遺漏要求和必需的信息。完整性也是一個(gè)需求應(yīng)具備的。發(fā)現(xiàn)缺少的信息很難，因?yàn)楦�本不存在。在SRS中將需求以分層目錄方式組織，將幫助評(píng)審人員理解功能性描述的結(jié)構(gòu)，使他們很容易指出遺失的東西。\r\n\r\n\r\n　　在需求抽象時(shí)，相對(duì)于系統(tǒng)功能，你過多的注意用戶的業(yè)務(wù)，將導(dǎo)致在需求的全局觀和引進(jìn)不是真正必需的需求上顯得不足。在需求抽象上，應(yīng)用用例方法會(huì)發(fā)揮很好的作用。能夠從不同角度察看需求的圖形分析模型也可以檢查出不完整性。\r\n\r\n\r\n　　如果你知道已缺少一些信息，使用TBD（to be determined）標(biāo)準(zhǔn)標(biāo)志可以突出這些缺陷，當(dāng)你在構(gòu)建產(chǎn)品的相關(guān)部分時(shí)，就可以從一個(gè)給定的需求集中解決所有的缺陷。\r\n\r\n\r\n　　一致性：一致性需求就是不要于其他的軟件需求或高級(jí)別的系統(tǒng)（商業(yè)）需求發(fā)生沖突。需求中的不一致必須在開發(fā)開始前得到解決。只有經(jīng)過調(diào)研才能確定哪些是正確的。修改需求時(shí)一定要謹(jǐn)慎，如果只審定修改的部分，沒有審定于修改相關(guān)的部分，就可能導(dǎo)致不一致性。\r\n\r\n\r\n　　可修改性：當(dāng)每個(gè)需求的要求修改了或維護(hù)其歷史更改時(shí)，你必須能夠?qū)彾⊿RS。也就是說每個(gè)需求必須相對(duì)于其他需求有其單獨(dú)的標(biāo)示和分開的說明，便于清晰的查閱。通過良好的組織可以使需求易于修改，如：將相關(guān)的需求分組，建立目錄表，索引，以及前后參考（照）。\r\n\r\n\r\n　　可追蹤：你應(yīng)能將一個(gè)軟件與其原始材料相對(duì)應(yīng)，如高級(jí)系統(tǒng)需求，用例，用戶的提議等。也能夠?qū)④浖�需求與設(shè)計(jì)元素，源代碼，用于構(gòu)造實(shí)現(xiàn)和驗(yàn)證需求的測(cè)試相對(duì)應(yīng)�？勺粉櫟男枨髴�(yīng)該具有獨(dú)立標(biāo)示，細(xì)密和結(jié)構(gòu)化的編寫，不應(yīng)過大，不應(yīng)是敘述性的文字和公告式的列表。\r\n\r\n(to be continued)