軟體工程/工具/軟體文件簡介

軟體文件 或 原始碼文件 是伴隨計算機軟體的書面文字。它要麼解釋軟體如何執行，要麼解釋如何使用它，並且對不同角色的人可能意味著不同的東西。

人員在軟體生命週期中的參與

文件是軟體工程的重要組成部分。文件型別包括

1. 需求 - 識別系統屬性、功能、特性或質量的陳述。這是對將要實現或已實現內容的基礎。
2. 架構/設計 - 軟體概述。包括與環境的關係和用於軟體元件設計的構建原則。
3. 技術 - 程式碼、演算法、介面和 API 的文件。
4. 終端使用者 - 為終端使用者、系統管理員和支援人員準備的手冊。
5. 市場營銷 - 如何營銷產品以及市場需求分析。

需求文件

需求文件是對特定軟體執行或將要執行的功能的描述。它在整個開發過程中使用，用於傳達軟體的功能或將要執行的功能。它也用作協議或協議基礎，說明軟體將要執行的功能。需求由參與軟體生產的每個人產生和使用：終端使用者、客戶、產品經理、專案經理、銷售、市場營銷、軟體架構師、可用性工程師、互動設計師、開發人員和測試人員等等。因此，需求文件有許多不同的目的。

需求有多種風格、符號和形式。需求可以是目標式的（例如，分散式工作環境），接近設計的（例如，可以透過右鍵單擊配置檔案並選擇“構建”功能來啟動構建），以及介於兩者之間的任何內容。它們可以指定為自然語言語句、繪製的圖形、詳細的數學公式以及它們的組合。

需求文件的多樣性和複雜性使其成為一個公認的挑戰。需求可能是隱性的，難以發現。很難確切地知道需要多少和哪種文件，以及可以留給架構和設計文件的內容，並且很難考慮到將要閱讀和使用文件的各種人員，從而知道如何記錄需求。因此，需求文件往往是不完整的（或不存在）。如果沒有適當的需求文件，軟體變更將變得更加困難，因此更易出錯（降低軟體質量）且耗時（成本高昂）。

對需求文件的需求通常與產品的複雜性、產品的影響以及軟體的預期壽命有關。如果軟體非常複雜或由多人開發（例如，行動電話軟體），需求可以幫助更好地傳達要實現的目標。如果軟體是安全關鍵的，並且會對人身安全造成負面影響（例如，核電系統、醫療裝置），通常需要更正式的需求文件。如果軟體預期壽命只有一個月或兩個月（例如，專門針對特定活動開發的非常小的行動電話應用程式），可能只需要很少的需求文件。如果軟體是第一個版本，之後會在此基礎上進行構建，則在管理軟體變更和驗證修改軟體時未破壞任何內容時，需求文件非常有用。

傳統上，需求在需求文件中指定（例如，使用文字處理應用程式和電子表格應用程式）。為了管理日益增長的需求文件複雜性和不斷變化的性質（以及一般意義上的軟體文件），人們提倡使用以資料庫為中心的系統和專門的需求管理工具。

架構/設計文件

架構文件是一種特殊的設計文件。從某種意義上說，架構文件是從程式碼派生的第三個衍生物（設計文件是第二個衍生物，程式碼文件是第一個衍生物）。架構文件中很少有內容是針對程式碼本身的。這些文件不描述如何編寫特定例程，甚至不描述為什麼該特定例程以其形式存在，而是僅概述了將促使該例程存在的總體要求。好的架構文件簡短描述細節，但解釋詳盡。它可能為更低級別的設計提出建議，但將實際的探索權衡研究留給其他文件。

另一種設計文件是比較文件或權衡研究。這通常以白皮書的形式出現。它專注於系統的某個特定方面，並提出替代方法。它可以處於使用者介面、程式碼、設計甚至架構級別。它將概述當前情況，描述一種或多種替代方案，並列舉每種方案的優缺點。好的權衡研究文件注重研究，清晰地表達其想法（不依賴於含糊的術語來炫耀讀者），最重要的是保持公正。它應該誠實地清楚地解釋它提供的任何解決方案的成本。權衡研究的目的是設計最佳解決方案，而不是推動特定觀點。沒有得出結論或得出結論，即沒有哪種替代方案比基線足夠好以至於需要更改，都是完全可以接受的。它應該被視為一項科學工作，而不是一種營銷手段。

企業軟體開發中設計文件非常重要的一個部分是資料庫設計文件 (DDD)。它包含概念、邏輯和物理設計元素。DDD 包含與資料庫互動的人員所需的形式資訊。編制它的目的是建立一個可在場景中所有參與者之間使用的通用來源。潛在使用者是

• 資料庫設計師
• 資料庫開發人員
• 資料庫管理員
• 應用程式設計師
• 應用程式開發人員

在談論關係型資料庫系統時，文件應包括以下部分

• 實體 - 關係模式，包括以下資訊及其明確定義
  • 實體集及其屬性
  • 關係及其屬性
  • 每個實體集的候選鍵
  • 基於屬性和元組的約束
• 關係模式，包括以下資訊
  • 表、屬性及其屬性
  • 檢視
  • 約束，例如主鍵、外部索引鍵
  • 引用約束的基數
  • 引用約束的級聯策略
  • 主鍵

包含所有將要被場景中所有參與者使用資訊非常重要。更新資料庫發生任何更改時的文件也同樣重要。

技術文件

這就是大多數程式設計師使用術語軟體文件時的意思。在建立軟體時，僅有程式碼是不夠的。必須有一些文字與之一起，以描述其預期操作的各個方面。程式碼文件必須完整，但不能過於冗長，以至於難以維護它們。API 編寫人員在為其所記錄的軟體應用程式或軟體產品提供許多操作方法和概述文件。開發人員、測試人員以及使用該軟體應用程式的最終客戶或客戶可能會使用此文件。如今，我們在電力、能源、交通運輸、網路、航空航天、安全、安保、工業自動化以及各種其他領域看到了很多高階應用程式。技術文件在這些組織中變得越來越重要，因為隨著架構的改變，基本和高階的資訊可能會隨著時間的推移而改變。因此，技術文件在近些年變得非常重要，特別是在軟體領域。

通常，可以使用 Doxygen、NDoc、javadoc、EiffelStudio、Sandcastle、ROBODoc、POD、TwinText 或 Universal Report 等工具自動生成程式碼文件，即它們從原始碼中提取註釋和軟體契約（如果存在），並建立以文字或 HTML 檔案等形式的參考手冊。程式碼文件通常組織成參考指南風格，使程式設計師可以快速查詢任意函式或類。

自動生成文件的想法對程式設計師來說很有吸引力，原因有很多。例如，因為它是從原始碼本身提取的（例如，透過註釋），程式設計師可以在參考程式碼時編寫它，並使用與建立原始碼相同的工具來製作文件。這使得保持文件更新變得容易得多。

當然，一個缺點是隻有程式設計師可以編輯這種文件，並且它依賴於他們來重新整理輸出（例如，透過執行 cron 作業來每晚更新文件）。有些人會將此歸類為優點而不是缺點。

唐納德·克努特堅持認為，文件可能是一個非常困難的後續過程，並且主張“文學程式設計”，即在與原始碼相同的時間和位置編寫文件，並透過自動方式提取。

闡釋程式設計是文學程式設計在實際程式設計環境中的實際應用的結果。闡釋正規化提出將原始碼和文件分別儲存。該正規化受產生 Kelp 的相同實驗發現的啟發。通常，軟體開發人員需要能夠建立和訪問不會成為原始檔本身一部分的資訊。這些註釋通常是幾個軟體開發活動的一部分，例如程式碼演練和移植，其中第三方原始碼以功能的方式進行分析。因此，註釋可以在軟體開發的任何階段幫助開發人員，在這些階段，正式的文件系統會阻礙進度。 Kelp 將註釋儲存在單獨的檔案中，動態地將資訊連結到原始碼。

使用者文件

與程式碼文件不同，使用者文件通常在程式的原始碼方面差異很大，而只是描述瞭如何使用它。

在軟體庫的情況下，程式碼文件和使用者文件可能有效地等效，並且值得合併，但對於一般應用程式來說，這並不經常發生。

通常，使用者文件描述了程式的每個功能，並幫助使用者實現這些功能。好的使用者文件還可以提供全面的故障排除幫助。使用者文件不能混淆並且必須保持最新，這一點非常重要。使用者文件不必以任何特定方式組織，但它們必須具有完整的索引，這一點非常重要。一致性和簡單性也很有價值。使用者文件被認為構成了指定軟體將執行的操作的合同。API 編寫者在編寫好的使用者文件方面非常出色，因為他們會非常瞭解軟體體系結構和使用的程式設計技術。另請參閱技術寫作。

使用者文件可以組織的三種主要方式是：

1. 教程：教程方法被認為對新使用者最有幫助，其中引導他們完成完成特定任務的每個步驟。
2. 主題：主題方法，其中章節或部分集中在某個特定感興趣的領域，對中級使用者來說更通用。有些作者更喜歡透過基於知識的文章來傳達他們的想法，以促進使用者需求。這種方法通常由動態行業（如資訊科技）採用，在該行業中，使用者群與故障排除需求高度相關^, 。
3. 列表或參考：組織原則的最後一種型別是簡單地按字母順序或邏輯分組列出命令或任務，通常透過交叉引用索引。後一種方法對高階使用者更有用，他們確切地知道他們正在尋找什麼樣的資訊。

使用者對軟體文件的常見抱怨是，只採用這三種方法中的一種，幾乎排除了其他兩種方法。通常，將為個人計算機提供的軟體文件限制為線上幫助，該幫助僅提供有關命令或選單項的參考資訊。輔導新使用者或幫助更有經驗的使用者充分利用程式的任務留給了私人出版商，這些出版商通常會從軟體開發人員那裡獲得大量幫助。

營銷文件

對於許多應用程式，必須提供一些宣傳材料來鼓勵臨時觀察者花更多時間瞭解產品。這種形式的文件有三個目的：

1. 激發潛在使用者對產品的興趣，並激發他們對參與該產品的願望。
2. 告知他們產品的確切功能，以便他們的期望與他們將獲得的功能一致。
3. 解釋該產品相對於其他替代方案的定位。

一種好的營銷技巧是提供清晰且令人難忘的口號，以體現我們希望傳達的觀點，並強調該程式與製造商提供的任何其他內容的互操作性。

外部連結

• kelp - 用於架構、設計和技術文件的原始碼註釋框架。
• ISO 文件標準委員會 - 制定使用者文件標準的國際標準化組織委員會。