在執行專案的時候，資訊軟體從業人員最痛苦的事，莫過於寫文件。一個專案下來有許多的文件要寫，例如專案管理計畫、建構管理計畫、品質保證計畫、風險管理計畫、開發計畫、測試計畫、教育訓練計畫、交付安裝計畫、監控計畫......你想得到事的都可以寫個計畫出來，在產品發展及產品與服務描述上，例如：系統規格文件、軟體需求規格文件、介面規格書文件、軟體設計說明文件、資料庫設計文件、系統架構、網路架構......同樣的，想得到的都可以寫成文件。但是，到底為什麼要寫文件，能不能不寫文件、就算要寫，文件又要寫成什麼樣子才是對的？

　　在個人的學習、實作與研究過程當中，有許多的起起伏伏與體認，從最初不懂得如何寫文件、經過以標準範本寫文件、直到現在寫文件已經不再要求開發人員一定要按照業界標準或某個範本，逐項逐條撰寫，這其實是對於系統工程不斷反芻的結果。

　　大家不妨先思考一個問題：在比較具有工程觀念的單位裡，都會要求建構管理(configuration management)這項工程常規(practice)。在納入建構管制機中的項目，大家很容易就想到：程式碼及文件。要管那些文件呢？計畫書、系統文件.....，只要能力夠，什麼都想納管。如果，再問到為什麼要管，大概都會答得出來：要維持版本一致性，避免用錯了版本，造成開發、測試、交付上的困擾。但是，建構管理真的是在管「文件」嗎？「建構管理在管理文件」這個概念，其實說對也不對！

　　看到這裡，大家可能要開始噓聲四起，但是整件事情的事實是：建構管理管的是「資料」，建構管理其實只是一套管理的程序與方法而已，被管到的資料是什麼呢？需求、設計、限制條件、時程、成本、工作的方法、程序、過程等等資料。這些資料的存在，是因為要產出專案的產品或服務，而專案之中有許多的客戶，不論是內在的客戶(團隊裡負責不同工作的成員、高階管理階層等)或是外部的客戶(業主、使用者等)，這些客戶會適地驗收或接收產品與服務，以執行及完成各自的職責或工作。而建構管理就是要運用識別、管制、狀態記述、稽核審查等等手段來維持這些資料的正確、一致、關聯正確……。

　　由專案之中有許多的參與者，有許許多多的客戶，每種客戶又有不同的「知的需求」，所以一定要有一個媒介，來進行溝通的工作。假設，某個客戶(系統設計師)需要業主的需求「資料」，以便進行設計的工作，如果你是系統分析師，你持有這些資料，請問，你會一次給他需要的所有資料呢，還是「先給功能需求，等到設計師問到介面需求時再給介面需求」呢？也許你不怕煩，不怕累，你熱愛你的工作，但是設計師可能不這麼認為，另外，也有可能會因為資料沒有一次給足，設計師就沒有辦法做全面性的思考，做不出好的設計，另外，分次給也可能會面臨各項資料版本不一致的問題。因此，比較好的做法就是建立一個資料版本的關聯性，也就是把相關的資料(正確的版本)串在一起，或放在一起，這樣的話，在各種工作(溝通、協調、執行專案任務)上就方便許多，也便於管理，而這個產出就是一個「文件」，例如我們將專案管理需要用到的資料(專案描述、時程、成本、風險管理、使用技術、專案成員資料……..)集合在一起，就成了專案管理「計畫書」，把功能需求、非功能性需求、介面需求、系統或軟體的限制條件、功能流描述等資料放在一起，就成了軟體需求規格「書」或「文件」。所以，我們談到「文件」，或者「紙張」(把資料記錄及保存在紙上)，其實是一個容器、或者是一個媒介，建構管理中對文件做識別、管制，其目的只是在簡化一些管理的工作，透過管理文件，進而達到「資料」的管理。但是現今，資訊技術、資訊媒體、管理工具都非常發達，是否還需要透過「文件」「紙張」媒體來管理「資料」其實是可以討論的。

　　從上面的討論，我們就可以了解，文件到底是什麼，到底用來做什麼，當然，也就知道為何在現在的一些標準，例如CNS 14837軟體生命週期過程國家標準中，沒有提到工程過程所產生之文件內容及格式(美國版本的IEEE/EIA 12207系列標準則有提列)了，因為文件可以因為需求的不同，而有不同的呈現，這包括使用的媒介、內容及格式。

　　在專案中，該寫那些文件呢？專案中，文件可以由業主來決定，由業主決定的話，最好不要只提名稱，要更具體地提出，內容、大綱，以及每個章節應包括的內容，如果，對於格式沒有特別的偏好，業主仍應說明該項文件要包含的項目為何，以及寫這些項目的目的，否則，建置商或供應商是沒有辦法寫文件的。如果業主認為文件的內容可談，亦應在專案初期(前一個月內)談定，以免因此而影響了整個專案的進程。

　　如果文件由建置商/供應商做決定，建置商/供應商應秉持品質至上的精神，好好提出相關的文件建議，包括名稱、格式及內容綱要。建置商/供應商切不可因為對於文件有建議權，就建議文件都不要寫，因為不寫文件，專案團隊就沒有辦法做有效的溝通、一致性地溝通，這將對專案造成重大的衝擊，更可能因此而無法完成專案，建置商/供應商切不可小覷。因為產品的實際狀況將很難掌控。

如何學習撰寫文件呢？最簡單的方式，就是拿現成的文件來抄寫修改，或是以標準範本作為藍本，撰寫自己的文件。但是，這種寫文件的方法常常會落入「閉門造車」的後果，我們要知道，文件是資料的集合，資料遠比文件範本的格式來得有價值，但是這是否意味著「範本無用」？非也，範本最大的用處除了框出整個文件的架構之外，它還可以導引你寫文件時的思考模式。所以，範本還是有其價值的，但在範本之外，如何產生裡面的資料，則又是基本功夫了。以專案管理計畫書為例，你要估成本、期程、產品的大小、技術難易度、風險管理做法，這其實是建構在系統工程之上的。你首先要了解未來要交付之產品或服務的結構，盡量地向下做區分成一樹狀結構，然後逐項去討論研究複雜度、關聯性等等問題，但這些基本功卻不是透過範本可以看得到的，因此這又是另外一個課題了。

----------------
引文:

軟體開發到底要寫什麼文件？到底該怎麼寫文件？我認為這些問題都可從國內外的標準或範例中得到答案，或從貴協會提供的教育訓練課程中學習到實務方法，甚至也有軟體工具可以協助。

但是根據我的經驗，國內許多軟體公司縱使是知道軟體開發到底要寫什麼文件？到底該怎麼寫文件？但是結果還是交不出合格的文件給客戶。

按照道理，客戶委託軟體公司訂製開發軟體系統(非套裝軟體)，要求承包商依照專案時程交付各種技術文件，是很合理的，就像營造商蓋房子也都會交付業主規劃圖、施工圖、管線圖 … 等，以便按圖施工、監造驗收及日後的管理與維護。

問題是軟體公司交付客戶技術文件時，一方面擔心公司的核心知識或機密外流，而不敢交付太詳細的內容，一方面也想故意保留一手，以便掌控客戶日後的軟體維護商機。如果這兩個心結不能克服，我相信問題依然會存在。

至於軟體公司要求軟體開發人員撰寫文件也一樣，軟體開發人員除了不愛寫文件或故意偷懶的原因以外，由於大多數的軟體公司過去以來都沒有建立垂直分工的機制，往往由同一個人包辦全部軟體的系統分析與設計開發，因此軟體開發人員擔心一旦將自己的核心知識透過文件交付出去，自己在公司的價值盡失，縱使是知道了軟體開發到底要寫什麼文件？到底該怎麼寫文件？也多是敷衍交差了事。如果這個心結不能克服，如果軟體分工開發的機制不建立，我相信問題也依然存在。

所以我認為解決問題的關鍵還是在於：「堅持要求」(客戶及軟體公司管理層)、以及「制度」與「管理」三個方面。

個人完全同意Fred的看法，只是我想要問一下有這種想法的軟體公司，他們是不是想過：到底軟體公司的核心競爭力是什麼？是擁有某一種半數位化的知識(原本應書面化成為規格或文件，卻因某些不健康的觀念而藏在人腦裡的東西)？ 還是能夠將非數位型式的知識加以數位化的能力？ 如果答案是後者，那麼他們為什麼要擔心“將那些半數位化的知識寫成文件會讓公司的核心知識外流”？ 如果答案是前者，那麼到底是誰擁有該半數位化的知識？是公司還是員工？ 答案很明顯，那決不會是公司。那麼公司的價值或核心競爭力到底是什麼？

對於那些擔心“一旦將自己的核心知識透過文件交付出去，自己在公司就會價值盡失”的軟體開發人員，我想問他們是否想過：他的價值是什麼？ 是能夠記住那些半數位的知識，還是他能夠將那些他要記住的東西寫成人人(專業人員)都看得懂的文件？如果答案是後者，那他怎麼會擔心“自己在公司就會價值盡失”？如果答案是前者，我要問他們：他真的可以用頭腦完全記住那些半數位化的知識嗎？即便他記得住，他又能記得多少？記多久？他會比一片十幾元的光碟片記得更多的資料，記得更久嗎？ 我想答案應該是很明顯的。

總而言之，如果還有哪家軟體公司或哪個軟體從業人員，還有Fred所說的那種心結，請想想您的公司或您的價值何在？

軟品協會專案管理師 周茂松

寫什麼文件？應該從兩方面下手：
(1)從業主（客戶）觀點面
(2)從公司內部知識管理面

(1)從業主（客戶）觀點面：
1.要清楚客戶類型，是真的需要一套可使用的軟體或想藉此竊取核心技術，如果業主的業務型態與軟體開發公司類似，大不了不要接此案就好了。
2.一開始便清楚界定，買賣雙方都同意的交付文件是哪些，所謂一分錢一分貨，而且最好是文件本身有對應的價錢！
3.文件的內容應該從使用者的方向來撰寫，而不是從設計者的觀點來撰寫，如此就可避免Kown-How外流！
4.當然，客戶對文件本身有審查權，可以對文件內容行使同意權。這點需要與業主充分溝通。
5.有關擔心kown-How被竊，或許簽約一開始，便以『法律合約』來規範，所謂防人之心不可無！

(2)從公司內部知識管理面
1. 公司不希望核心技術被掌握在某些人手中，因此，管理者有義務要求工程師建立完整技術文件，以免因某人離職而技術喪失。這時，管理者盡可能要求軟體開發文件就要鉅細靡遺紀錄此類文件，文件撰寫就要從設計者觀點下手。管理者可以結合績效考核，威脅利誘方式要求工程師一定要寫！此類文件不需要交給業主
2. 那麼工程師是否因為要寫兩套文件而感受到特別累呢？其實不然，專案計畫類的文件應該不會有什麼Kownhow，只有設計類文件才有，這時，可以要求先以『鉅細靡遺』方式撰寫，最後，交給客戶的是經過剪裁後的版本！
3. 軟體公司的命脈，不可避免會因為某些人的去留而受到影響，公司既不希望核心能力被『綁架』，也不希望核心技術外流，影響是大是小端看公司制度建立得如何。

阿吉

寫文件非常重要, 在目前多變的時代, 需求常會變, 需求一變, 程式碼就要改變, 文件也要修正. 文件本身也是產品, 會消耗公司成本, 這是一定要有的認知.

另外, 程式碼本身也是文件, 是工程人員花費心力所做的藍圖; compiler和linker就是工廠, 把藍圖製造成軟體產品. 有了這份認知之後, 我們便知道, 程式碼的註解比程式文件還重要 .