Link Search Menu Expand Document
AIEE

系統程式開發文件

Table of contents

背景

OpenAI的答覆

一般良好管理的系統開發公司，對於程式文件的撰寫通常有以下幾項規定或最佳實踐：

1. 結構清晰

文件應包括:

  • 背景資訊、
  • 功能需求、
  • 技術架構設計、
  • API 說明、
  • 使用說明、
  • 測試計畫及
  • 例外處理等章節。

2. 統一格式

•	使用標準化的文檔模板，包括固定的標題層級、命名規則和代碼格式規範。
3.	技術詳盡
•	清楚記錄程式邏輯、數據流程圖、類別圖及介面規範，並包括參數定義與返回值說明。
4.	維護易讀性
•	文件應清楚標示版本歷史、修改紀錄及責任人，確保文件可持續更新。
5.	內部審核
•	文件在提交前需經過技術團隊或專案經理的審核，保證內容準確性。
6.	與代碼同步
•	文件內容應反映最新代碼，避免過時，並建立自動生成或更新文檔的流程。

這些規範不僅能提升開發效率，還能確保系統的可維護性和知識傳遞的順暢。

規範與範例

在系統開發領域，良好的文件撰寫對於專案的成功至關重要。以下是一般資訊系統開發公司在文件撰寫方面的常見規定： 1. 文件類型與內容： • 軟體開發計畫書（SDP）：規劃與管理軟體發展流程，說明系統目標、範圍、架構、環境、時程等。  • 軟體需求規格書（SRS）：描述最終使用者的需求，作為未來測試及驗收的依據。  • 軟體設計規格書（SDD）：詳細描述系統的設計，包括架構、模組、介面等。 • 軟體測試計畫書（STP）：制定測試策略、範圍、方法和資源，以確保系統符合需求。 • 軟體使用手冊：提供使用者操作指引，確保系統的有效使用。 2. 文件格式與標準： • 統一格式：使用公司制定的模板，確保文件的一致性和專業性。 • 版本控制：對文件進行版本管理，記錄修改歷史，確保團隊成員使用最新版本。  • 清晰明瞭：使用簡潔的語言和圖表，確保內容易於理解。 3. 文件審核與維護： • 定期審核：定期檢查文件的準確性和完整性，確保其與實際開發進度一致。 • 持續更新：隨著專案的進展，及時更新文件，反映最新的需求和設計變更。 4. 文件的使用與溝通： • 團隊協作：確保所有相關人員了解並遵循文件中的規定，促進有效溝通。 • 客戶交流：與客戶分享相關文件，確保需求的準確傳達和確認。

優秀範例

以下是一些公開的系統開發文件範例，可供參考：

  • 資訊系統開發管理文件
  • 前端開發設計文件
    • 介紹前端開發設計文件應包含的內容，如概述、UX設計、變更範圍、元件設計等。 
  • 產品需求與規格文件
    • 提供產品經理在撰寫產品需求與規格文件時的問題、心法與實作建議。 
  • 糕餅業案例 這些範例可作為撰寫系統開發文件的參考，協助提升文件品質和專案管理效率。

ISO的建議

ISO（國際標準化組織）在資訊技術和軟體工程的標準中，對於系統開發文件提供了多項建議，特別是在 ISO/IEC 12207:2017（系統與軟體工程—軟體生命週期流程）和 ISO/IEC/IEEE 15289:2019（系統與軟體工程—生命週期過程文件）中。以下是主要建議的摘要：

1. 文件的類型與內容

ISO 建議系統開發文件應涵蓋以下方面，並根據生命週期階段進行分層撰寫：

需求分析階段 • 需求規格文件（Software Requirement Specification, SRS） • 描述系統或軟體的功能需求和非功能需求。 • 必須清楚、完整、無歧義，並且便於測試和驗證。 • 使用者需求文件 • 闡明最終使用者的業務目標與期望。

設計與開發階段 • 架構設計文件（System/Software Design Description, SDD） • 描述系統的總體設計、模組劃分和介面規範。 • 使用統一建模語言（UML）等工具輔助設計文件的撰寫。 • 詳細設計文件 • 提供模組內部的詳細邏輯設計與數據結構。

測試與驗證階段 • 測試計畫書（Software Test Plan, STP） • 定義測試範圍、測試方法、測試環境和資源需求。 • 測試報告（Software Test Report, STR） • 詳述測試結果和是否滿足需求的結論。

運維與交付階段 • 使用手冊 • 針對最終用戶，提供易於操作的說明。 • 系統運維手冊 • 針對系統管理員，詳細說明系統配置、備份、升級等操作。

2. 文件管理建議

ISO 特別強調文件管理的重要性，包括以下規範：

標準化 • 使用統一的文件模板與術語，確保一致性。 • 標題、章節編號和格式需清晰明確，符合企業內部標準或 ISO 標準。

版本控制 • 每份文件必須具有版本號與修改記錄，便於追溯與管理。 • 使用版本管理工具（如 Git）實現自動化版本控制。

可追溯性 • 文件之間的關聯（例如需求與測試案例）需明確記錄，方便追溯問題來源。 • 可追溯性矩陣（Traceability Matrix）是一個常見工具。

  1. 文件的審核與驗證

ISO/IEC 要求系統開發文件在撰寫後需進行以下幾項驗證： • 內部審核：由內部開發與測試團隊確認文件的準確性和完整性。 • 外部驗證：邀請用戶或第三方檢查文件是否滿足業務需求和標準規範。 • 正式簽署：文件通過審核後應有簽署記錄，作為正式檔案歸檔。

  1. 文件的維護與更新 • 文件需要隨專案進展進行動態更新，特別是在需求變更時，相關設計與測試文件必須同步修訂。 • 在系統交付後，應持續維護運維文檔，以反映系統升級或變更情況。

  2. 其他關鍵建議 • 可讀性與簡潔性：文件應避免冗長，保持簡潔和專業，便於技術人員和非技術用戶理解。 • 使用圖表與工具：適當使用流程圖、數據流圖、UML 等可視化工具輔助說明複雜內容。 • 數位化管理：推薦使用文件管理系統（如 Confluence、SharePoint）進行數位化存儲與協作。

參考文件

如果需要更詳細的指引，可以參考以下 ISO 標準： 1. ISO/IEC 12207:2017 - 軟體生命週期流程標準 2. ISO/IEC/IEEE 15289:2019 - 生命週期過程中的文件管理 3. ISO/IEC 25010:2011 - 系統與軟體品質模型

這些標準不僅幫助建立文件管理的最佳實踐，還能提升專案的效率與透明度。

有關文件發布平台的考量

是的，Confluence 和 SharePoint 都可以建置在地端，並且支援企業內部的文件管理需求。但如果您已經有 VuePress 和 Gitea 自動發布系統，它們的功能是否相當取決於您實際的使用場景和需求。以下是詳細比較與說明：

1. Confluence 與 SharePoint 的地端部署

Confluence • 地端版本：可使用 Confluence Data Center 或已終止的 Confluence Server（只提供維護，未來推薦 Data Center）。 • 適用場景：專為團隊協作、知識管理和文件撰寫設計，具有靈活的編輯器、模板功能，支持即時協作。 • 部署要求：需要安裝在企業內部伺服器或虛擬機環境，並配置 PostgreSQL、MySQL 等資料庫。 • 功能亮點： • 版本控制與恢復 • 強大的權限管理 • 插件與擴展（例如 Jira 整合）

SharePoint • 地端版本：可以部署 SharePoint Server，但許多企業更傾向使用雲端版的 SharePoint Online。 • 適用場景：適用於文件儲存與共享，具備更強大的文件協作功能，與 Microsoft 生態系統（如 Office 365）整合。 • 部署要求：需要運行在 Windows Server 環境，並依賴 SQL Server 資料庫。 • 功能亮點： • 高度整合 Office 應用 • 支援自動化流程（如 Power Automate） • 文件版本管理與檔案夾層級權限設定

2. VuePress 與 Gitea 的自動發布系統功能比較

您目前的系統基於 VuePress（文件生成）和 Gitea（版本控制），它們的功能偏向開發者友好，但與 Confluence 或 SharePoint 存在以下主要差異：

相似功能 1. 版本控制與發布 • Gitea 提供類似 GitHub 的版本控制功能，適合開發者管理程式碼與文件版本。 • VuePress 支援將 Markdown 轉換成靜態網站，結合 Gitea 或 CI/CD 工具可實現自動發布。 2. 文件組織與檢索 • VuePress 的目錄結構靈活，支持搜索功能。 • Gitea 則依賴 Git 檔案結構，對於熟悉 Git 的團隊來說非常高效。

不足之處 1. 即時協作 • VuePress 和 Gitea 缺乏即時多人編輯功能，團隊成員無法像在 Confluence 中那樣同步撰寫與檢視變更。 2. 權限管理 • VuePress 與 Gitea 的權限管理較為基本，難以做到像 SharePoint 那樣細緻的層級設定（例如文件夾與文件層級的權限）。 3. 功能整合 • VuePress 與 Gitea 偏重技術導向，對於非技術部門不如 Confluence 或 SharePoint 直觀。 • 缺乏與 Office 文件格式的直接整合能力（如 Word 或 Excel）。

3. 適用場景與建議

如果維持現有 VuePress 與 Gitea 系統： • 適用場景： • 技術文件與開發團隊知識共享。 • 文件由開發人員主導撰寫與發布。 • 改進建議： 1. 增加插件以強化 Markdown 編輯功能（例如 Mermaid.js 用於繪製圖表）。 2. 與 CI/CD 系統（如 GitLab CI 或 Jenkins）整合，進一步提升發布效率。 3. 引入全文搜索工具（如 ElasticSearch）加強檔案檢索功能。

如果導入 Confluence 或 SharePoint： • 適用場景： • 跨部門協作，需要直觀的使用者介面和非技術用戶參與。 • 強調權限管理、版本控制和多格式文件整合。 • 建議做法： 1. 保留 VuePress 和 Gitea 用於技術文件的開發與發布；同時將非技術文件轉移到 Confluence 或 SharePoint。 2. 考慮地端與雲端整合，例如將 SharePoint 作為文件存儲中心，VuePress 生成靜態網站的文件進行同步。

4. 最終建議

如果您的主要需求是跨部門的文件協作與管理，並且希望提供給非技術同仁使用，推薦採用 Confluence 或 SharePoint 作為補充。 但若您的核心需求是面向開發者，且目前系統已經穩定運行，繼續優化 VuePress 與 Gitea 會更具成本效益。