為你寫下這份文件，陪著你和專案一起往下走。

如果你 忘了Code
就讓文件 代替我
如果你 記得Code
你和Code 就好過

有時候公司會把員工斷捨離，員工也會斷捨離公司。

技術人員雖然會離開，但要讓知識可以留下來

在前一篇文章中提到了問問題的重要性，這篇文章想來談談在職場中的另外一個技能 文件撰寫。

對軟體開發來說寫好文件是一項必備技能，不論是在新人培養、部門技術分享、專案規格溝通，甚至離職交接，優秀的文件撰寫能夠使團隊運作更順暢。

寫好文件其實我覺得不太困難，大家從小到大都寫了很多報告，但到了職場之後卻又把過往的訓練拋棄我覺得有點可惜。

長久下來，我認為一份好的文件確認兩個重點通常就能夠有不錯的表現:

1. 文件目的
2. 讀文件的對象

寫好文件被誇獎其實也會有成就感

文件撰寫目的

在開始動手之前，必須確認為什麼要寫這份文件？

• 文件的目的是為了資訊的傳遞

在資訊傳遞上最重要的是持續維持大家的 context

• 事前少量揭露，事後的總結
• 確認對方想法
• 確認議題結束

希望達成的目標與結果是什麼？是為了傳達信息、教育讀者、解決問題還是其他原因？

• 指明文件預期的結果: 例如讀者將能夠理解某個概念、執行特定的操作，或解決特定的問題
• 預期讀者獲得什麼資訊: 確保文件中包含讀者最需要的資訊

文件撰寫的目標對象

訊息的投放不管在哪種領域中，了解你的目標對象並針對對象優化都是一門課題。

底下是動筆前值得思考的問題:

• 誰會看這份文件？
• 如何使用這份文件？
• 預期在這份文件得到哪些資訊？
• 習慣的文件格式是什麼樣子？

確定你的目標對象，並考慮他們的背景知識和需求來調整文件內容和風格，確保更有效地傳達資訊。

舉三個不同對象的例子:

1. 專案經理 (PM): 文件的目的是要協助對更上層交差協助他們更好地理解和管理專案，透過總結列點、淺顯易懂的說明、運用圖文穿插就會是較好的文件撰寫方式
2. 接手工程師: 文件需要提供足夠的資訊，這個部分可以參考開源專案的 README.md 或 Quick Start Guide，目標是協助對象在短時間內了解專案的關鍵知識和步驟
3. 針對大眾: 部落格教學文章，可能需要提供可複製和貼上的程式碼、關鍵步驟的圖文解釋，並提供完整的參考資料供讀者深入學習

文件分類

• 是主要文件還是參考文件: 文件可能是主要的指南也可能僅作為參考，標示清楚可以幫助讀者理解用途
• 習慣的文件格式: 考慮到讀者可能已經習慣了某種文件格式，使用這種格式可能更容易被接受

根據不同的需求，選擇適當的文件類型能夠更好地傳遞訊息。

文件可以分為多種類型，例如專案計劃、需求規格、設計文件、程式碼註釋、測試計劃和報告、使用者文件以及快速入門指南。

• 專案計劃: 專案計劃文件包括目標、時程表、預算、資源分配以及負責人
• 需求規格: 具體明確的描述專案的功能和功能需求，以便開發團隊能夠準確理解和實做
• 設計文件: 描述系統的結構和流程，包含系統架構圖、數據庫設計和界面設計
• 程式碼註釋: 在寫程式碼寫到自己都看不太懂的，務必寫詳細的註釋
• 測試計劃和報告: 寫測試劇本說明測試的範圍、測試用例和預期結果
• 使用者文件：特規的地方該如何使用
• 快速入門：每個專案都一定要有，特別是如果有自定義的腳本時也要特別說明

文件的好處

相信大家會來看這個部落格，大部分都是在網路或科技相關領域工作，所以就先用工程師的角度來談談，文件之於專案進行就像是框架之於應用開發，對工程師來說使用框架有什麼好處?

• 省時間: 不用再研究和交代基礎建設類問題，離職交接很快
• 學觀念: 能透過框架學習準則，了解目前業界遇到了什麼問題
• 抄作業: 通常框架說明書也會提供 Best Practices

其實相關的優點是類似的，對於專案進行，文件有什麼好處?

• 省時間: 如果同樣一份文件給所有人看，只有一個人看不懂? 能找出瓶頸也很棒，剩下讓能處理的處理?
• 學觀念: 看過前人遺毒後，能了解公司遇到問題是怎麼解決的
• 抄作業: 寫完一遍可以廣泛用在各種教育訓練、離職交接、進度報告文件上

寫好文件會有哪些好處?

• 同時和多人進行非同步的溝通
• 撰寫一次卻能到處使用

同時和多人進行非同步的溝通

當然面對面有無法取代的好處，但我認為技術相關畢竟是密度較高的訊息，口語的溝通比起文件溝通又更難一些，為什麼口語又更難，因為文件可以附上參考資料，口語還要在訊息投放時針對受眾即時的進行轉譯和客製化，也就是花很多時間降維到足夠對方吸收為止，且還要確認對方理解後才能繼續往下。

寫文件的好處是花時間寫好一次就可以同時跟很多需要資訊的人進行溝通，而不需要在受限制的時間、地點下進行有失敗機率的訊息同步，文件原則上一群人有八成能看懂我們就不需要再花時間處理剩下兩成，除非那兩成是你的老闆。

一次撰寫，到處使用 (Write Once Use Everywhere)

職場上的文件有另外一個顯而易見的好處，就是能夠一稿多投。

舉例來說為了讓同事一起成長而決定在部門內分享新知或是專案處理方式，不但可以正大光明用上班時間來做自己想做的事情，還可以順便當作提早離職交接的概念，因為到時候離職也是可以講同一份文件，寫好一份文件，我最常一稿多投的情境有

• 進度報告
• 讀書會知識分享
• 專案回顧
• 離職交接