項目文件？ [關閉]

Question

我為CMMI 5級認證公司工作，我討厭的一件事是我們准備的文件數量（作為程序員，我已經討厭過文件）。 我們有很多很多文件，比如PID（項目啟動文檔），業務需求，系統需求，技術規范，代碼審查清單，問題日志，缺陷日志，配置管理計划，配置管理檢查表，發布文檔和批次...

這些文檔中有近90％只是為了QA審計而完成:) ..您認為項目最重要的文檔是什么？ 從長遠來看，其他開發人員可以使用哪些文檔？

請在此分享您的良好做法。 我想將它們用於我自己的項目或我計划從長遠來看的公司。

謝謝

Answer 1

關鍵文件是一個很好的功能規范。 系統應該只有一個參考文檔。

每當有人更改系統或界面時，過度使用的文檔會增加大量的小需求和規范文檔。 對於任何復雜的系統，不久你就可以將你的規范分布在幾百個單詞，excel，visio甚至powerpoint文件中。 當發生這種情況時，您將無法確定當前的內容，甚至是否找到並確定了所有相關文檔。

BRD-SRD-Tech規范進展是基於業務簽署BRD的假設，業務分析師根據BRD中記錄的要求簽署SRD並且技術規范與SRD簽署。 這會生成一個簽名網絡，多個包含冗余信息的文檔，並使規范文檔保持最新變得困難和笨拙。

因此，后續需求文檔往往采取一系列變更請求和補充要求以及規范文檔的形式，每個都有自己的簽名和審計流程。 您獲得了CYA和審計跟蹤（或至少是審計跟蹤的外觀），但您失去了清晰度。 現在沒有關於該系統的明確參考文件，並且很難確定任何特定活動的當前或相關內容。 最終結果是您的業務分析過程陷入了法醫研究的困境，這增加了交付計划的開銷和延遲。

應該以這樣的方式構建規范文檔，即對任何給定的系統或子系統都有一個明確的引用。 該文件應保持最新和版本。 獲得一個很好的技術文檔工具，如Framemaker，因此您的流程可以擴展，並且文檔具有一些缺乏Word的結構完整性。

Answer 2

對我來說，我使用的唯一真實文件是規范。 越詳細越好。 然而，它不需要一次完成所有，並且它不需要特別正式。 對我來說，比檢查和簽名以及雙重檢查和雙重簽名的文檔總是能夠獲得最新版本的文檔更有用。 能夠與人們談論他們所寫的內容，並在任何模棱兩可的情況下做出決定。 這對我來說比其他任何東西都更有用。

總結一下：規范是我發現的唯一有用的文檔，但是與讓項目經理了解所提出的系統內部相比，它可以根據他們所知道的做出明智的決策。

Answer 3

文檔就像豆腐 - 大多數人都討厭它，直到他們意識到在合適的條件下，它真的很好。

問題在於您考慮的文檔主要是出於文檔的考慮。 作為開發人員，您在所生成的文檔中看不到任何直接價值，因為您知道在沒有您需要制作的所有TPS報告的情況下，您可以完成工作。

不幸的是，我要打賭，在一家你一直被迫吃生豆腐的公司里，你無法做很多事情。 您可能只需要填寫並編寫公司所需的文檔，但您至少可以做一件事......您可以編寫至少對您有用的文檔，並且可以將它們與您一起傳遞維護它的其他人的代碼。

除了內聯文檔之外，您還可以設置一個wiki供自己和團隊成員使用。 這種類型的文檔是可搜索的 ，這對開發人員來說已經是一個很大的優勢，而且它更像是一個活文檔，而不是你必須編寫的類似家庭作業的文件。 您已經發布到SO，所以只需將您的文檔視為將知識集中在一個更有用的地方。

Answer 4

您認為項目最重要的文件是什么？

不同的人有不同的需求：例如，所有者需要的文件（例如商業合同）與QA所需的文件不同。

從長遠來看，其他開發人員可以使用哪些文檔？

IMO最重要的文檔（源代碼除外）是功能規范：因為軟件應該做什么（而不是它正在做什么）是一件不一定是逆向工程的東西。 另請參見優秀開發人員如何避免創建具有低總線命中系數的代碼？

Answer 5

用戶故事，燃盡圖表，代碼

Answer 6

從項目的角度來看，最重要的文件是通常包含計划一詞的文件，例如項目計划，配置管理計划，質量計划等。

您所描述的內容在流程改進中很常見，通常會對兩個主要原因做出響應。 一個是系統真的是過度使用並阻礙了正在進行的實際工作。 另一個問題實際上是在您的問題中回答的：並不是文檔只是為了審計而完成，而您的重點不僅僅是對其他開發人員的文檔有用，而是對項目或整個公司有用。

人們通常從它自己的角度看待事物，有時候需要看一般情況。

Answer 7

我是舊4 + 1觀點的粉絲：

• 用例視圖（a / k / a用戶故事）。 有幾種形式：正確的使用案例，沒有明確定義的前瞻性用例和需要分解的史詩。

• 邏輯視圖。 “靜態”視圖。 UML類圖等在這里作為設計文檔很好地工作。 這還包括各種協議的請求和響應格式。 這是我們記錄RESTful請求和響應的地方。 這包括REST URI設計。

• 流程視圖。 “動態”視圖。 用於設計文檔的UML活動圖，序列圖和狀態圖等。 在某些情況下，簡單的敘述效果很好。 在其他情況下，存在狀態設計模式，它需要類圖和狀態圖的組合來顯示有狀態對象如何交互。

  這還包括協議（例如REST）。 這是我們為各種REST請求定義任何特殊處理的地方。

  這還包括身份驗證或授權規則，以及安全性，日志記錄等任何其他交叉方面。

• 組件視圖。 我們正在為部署而構建的部分。 這包括我們依賴的東西，模塊和包的結構等。這通常是一個簡單的組件圖或組件列表及其依賴項。

• 部署視圖。 我們嘗試從部署的代碼中生成此內容。 由於我們使用的是Python，因此我們使用epydoc來創建API文檔。 我們還使用Sphinx將模塊文檔導入到該軟件視圖中。

  這還包括參數，設置和配置詳細信息。

然而，這還不夠。

當項目開始時，你必須通過一系列沖刺來解決這個問題。

1. 第一個sprint只構建用例視圖。

2. 隨后的沖刺構建了一個“架構”來實現用例。 體系結構文檔具有4 + 1個視圖，但處於高級抽象級別。 它總結了模型模式的結構，請求和回復，RESTful處理，其他處理，預期的組件等。它從未有過部署視圖。 我們通常將操作員指南和API文檔作為體系結構的部署視圖。

3. 然后，設計和構造沖刺為各種組件構建（和更新）詳細的4 + 1視圖文檔。

4. 然后發布sprint構建（並更新）部署視圖。