軟體工程/實現/文件簡介

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

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

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

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 文件標準委員會 - 制定使用者文件標準的國際標準化組織委員會。