我們為了完成功能已經竭盡心力，實在沒有多餘的體力去寫技術文件；因此有些人在交付功能給同事時，文件在有與沒有之間，有時甚至直接用口述、Demo 代替。

這種情況在一個人獨立作業的專案更為常見，因為他覺得這份專案就只有自己一個人維護，技術文件是要寫給誰看？

身為工程師，我也曾有過這些想法；但隨著經手的專案越來越多，我深刻理解到「技術文件」是一個無法逃避的任務。

沒寫技術文件會發生什麼事？

下面列出幾點常見的問題：

1. 專案的核心工程師離職後，如果沒人了解這個專案過去的歷史，那就只能等它自行炸裂。
2. 就算離職前有做交接，相信我，一定會漏東漏西，不要相信人類的記憶力。
3. 就算是獨自開發的專案，往往一年後需要維護、擴充時，你會懷疑自己有失憶症。

了解沒寫技術文件會埋下的未爆彈後，就算不為接手的工程師考慮，也為將來的自己寫一下吧！

為什麼會沒人撰寫、維護技術文件？

大部分是公司文化的問題。

最常見的原因是「專案時程太趕」，功能都快要做不完了，誰還有時間寫文件？如果產品能夠順利交付，更不會有人在事後把文件補齊。

另一個因素是「大家不知道文件該怎麼寫」，除非有前人的範例可以參考，不然每個人認定文件該有的內容都是不一樣的。

過去筆者有寫一篇部落格，分享 README.md 對專案的重要性，有興趣的朋友可以參考看看。

想跟大家聊聊

平常大家有寫技術文件的習慣嗎？

規劃任務時，有把撰寫文件的時間考慮進去嗎？又或是額外開一張寫文件的 Ticket 呢？

過去在工作上，有因爲缺少技術文件而發生的悲劇嗎？歡迎大家在留言區分享自己的血淚史喔！

身為工程師，我理解大部分的人都想把精力放在寫出更好的程式，但專案能否長期發展，其實是取決於「文件」；如果文件亂七八糟，或者甚至根本沒有制式文件，那這個專案的未來發展性堪憂。

從管理的角度來說，我們要去思考：「如果負責專案的工程師明天就不在了，這個專案能否進行下去？」

大綱
一、為什麼 README.md 很重要？
二、有哪些是 README.md 一定要提供的資訊？
 ➤ 專案介紹 — Description
 ➤ 運行環境需求 — Requirement
 ➤ 環境檔（.env）有哪些欄位要自己填寫 — .env Setting
 ➤ 在 Local 端的安裝＆運行步驟 — Build Setup(Local)
 ➤ 在 Server 端的安裝＆驗證步驟- Build Setup(Server)
 ➤ 可提供支援的同仁 ── Support
 ➤ 注意事項 — Warning
三、如果 README.md 有這些資訊，會讓日後維運更加順利
 ➤ 系統架構圖 — System architecture
 ➤ 使用者操作手冊 — User Manual
 ➤ Demo 影片 — Demo Video
 ➤ UI/UX 設計稿 — UI/UX Design
 ➤ Function map
 ➤ 單元測試、整合測試 — Unit Testing、Integration Testing

一、為什麼 README.md 很重要？

因為開發人員第一次接觸專案時，就是透過 README.md 來了解的。

它就像是一張專案的地圖，如果破損、缺乏維護，那踏上旅途的人勢必會遇上迷航、陷阱。

在沒有律定 README.md 該有什麼內容時，每個人都是自由發揮；除了內容可能有短缺外，每份專案的撰寫風格也不盡相同，因此想透過這篇文章律定基礎架構。

這邊提醒讀者，本篇文章所建議的 README.md 內容是提供給「內部開發人員」看的；如果你的專案是對外開放，部分內容請自行斟酌。

二、有哪些是 README.md 一定要提供的資訊？

下面列出的項目，是筆者認為對第一次接觸專案、準備維護專案的人有幫助的資訊。

專案介紹 ── Description

簡述專案目標，讓第一次接觸的人也能在短時間初步了解專案（如果使用到少見的專有名詞，請附加說明）。

如果是前後端分離的專案，請附上前端/後端的專案連結。

運行環境需求 ── Requirement

描述這個專案運行所需要的環境，比如說：

• 前端（Frontend）：NVM、Yarn、Node.js
• 後端（Backend）：PHP、Composer、Laravel、MySQL

隨著技術進步，各項工具的版本不斷更迭；因此建議要附上能讓專案順利運行的「版本」，因為許多工具並沒有向下相容。

環境檔（.env）有哪些欄位要自己填寫 ── .env Setting

以後端來說，涉及機密、隱私、個人化的參數會需要自己填寫，比如：

1. DB 帳號密碼、IP、Port
2. JWT 有效期限
3. Mail 相關參數
4. Storage 路徑

在 Local 端的安裝＆運行步驟 ── Build Setup (Local)

是那種「複製貼上」就能夠順利安裝的步驟，可以放一些參考連結，但不要讓使用者需要去閱讀官方文檔才知道怎麼安裝。

以後端舉例，指令需至少包含如下內容：

1. 專案安裝步驟
2. DB Migration
3. DB Seeder
4. 運行專案

如果採前後端分離，可以附上 POSTMAN 的 collection 方便前端驗證。

在 Server 端的安裝＆驗證步驟 ── Build Setup (Server)

如果不是採取自動部署的策略，那筆者建議紀錄如下內容：

1. 專案運行所需套件，及其對應的指令
2. 伺服器端參數（ex：API 最長可執行時間、可上傳檔案容量限制、單個 IP 每分鐘存取次數）
3. 不同環境對應的 Server ip
4. 相關參數調整後，重啟使其生效的指令
5. 部署完成後，可以透過什麼方式（工具）驗證功能皆如預期運行

可提供支援的同仁 ── Support

讓初次接觸專案的人知道遇到問題可以找誰詢問，建議在這個部分放上開發人員的聯絡方式（ex：座位、email）。

有時問題可能有其歷史背景，所以可以用附註形式，放上了解這份專案歷史的同仁（ex：主管、負責的 PM）。

注意事項 ── Warning

每個專案或多或少都會有一些特別的設計，時間拉長難免遺忘，建議把他們記錄下來，比如：

1. 如果 API 文檔是用指令產生的，請記得記錄下來
2. 如果有設計排程（Schedule），把觸發的時間點列出
3. 前端在不同環境的建立指令（Script）
4. 如果用到特別的套件，建議簡單說明在什麼時機應用，並放上官方文檔連結
5. 專案的授權條款（License）

三、如果 README.md 有這些資訊，會讓日後維運更加順利

系統架構圖 ── System architecture

如果專案結構複雜，或是需要串接多個系統，那建議放上系統架構圖，否則接手的工程師會需要花很多時間去研究他們之間的關聯性。

使用者操作手冊 ── User Manual

每份專案都一定要製作使用者操作手冊，否則 PM、工程師會不停被重複的問題打擾；有了這份手冊後，之後負責維運的工程師也能更快上手。

形式可以是 Wiki、Word…等等，讓使用者方便閱讀為第一優先。

Demo 影片── Demo Video

如果可以，建議在專案完成後錄製「簡單」的 Demo 影片；主要目的是讓工程師知曉專案「正常」的狀況下應該長什麼樣子。

有時專案看似順利啟動了，但實際上部分功能是不完整的（ex：前端順利啟動了，但 WebSocket 異常）。

UI/UX 設計稿 ── UI/UX Design

放上 Wireframe、Mockup、Prototype 等設計稿連結（如果有的話）

Function map

通常會以心智圖來呈現，PM 可以透過它讓工程師快速了解、評估初期的功能。

在遇到需求要新增或變更時，有這張圖工程師能也更快回憶，並掌握重點。

GitMind 是個不錯的工具，推薦大家使用看看。

單元測試、整合測試 ── Unit Testing、Integration Testing

專案的穩定，是建立在有寫測試程式的前提下；否則系統很容易因為需求的新增、變更，而導致過去的功能毀損。

在測試方面，除了「整體」的測試外，有時我們只需要測試「特定功能」；可以把常用的測試指令紀錄在這裡（ex：邏輯複雜、關聯廣泛的測試）。

以上內容是筆者過去專案經驗的彙整，若有未盡之處，歡迎留言補充。

工程師血淚史
▋ 團隊在系統開發上遇到了哪些問題
▋ 需求不斷變更，到底哪個環節出錯了
▋ 當 Scrum Master 跟 PM 同時存在，權力與責任該如何區分？
▋ 如果沒有明確的開發流程，團隊將會無所適從
▋ 你知道對專案來說，README.md 有多麼重要嗎？(本篇)

一、遠端工作 — VPN 連線

因為疫情關係越來越多公司的 IT 部門採取遠端工作，但許多工作上的資料以及開發環境都在公司內網，所以在新人報到前你需要提供給他們可以使用內網的 VPN，主要是提供 PPTP、L2TP 這兩種。

特別注意 mac 是不支持 PPTP 的連線，需要安裝其他 VPN 軟體才能使用，筆者是安裝 shimo 這個軟體

二、註冊公司內部協作平台的帳號

如果公司內部有專案管理系統(ex：Jira、Zentao、Redmine)或是軟體開發平台(ex：GitLab)，請先幫他們完成註冊，並列成清單讓他方便登入。

三、整理需要讓對方遠端登入的伺服器

通常工程師在發布功能時會經過三道關卡：

• DEV：工程師內部開發測試使用，功能都尚未測試
• QA：工程師開發完成並且通過自己的 test case 驗證，此階段會給公司專門的團隊進行各式各樣的測試
• PROD：測試部門確認功能穩定且通過壓力測試後就能發布到正式的 Server

這三個情境會對應到不同的 server，如果新人發布到錯誤的 server 會造成不可挽回的後果，所以建議 PROD 的 server 等新人熟悉作業流程後再給他登入的權限。

在報到第一天時用公司的電腦產生 ssh key，並設定到 DEV、QA 的 server 上面，建議設定 alias name 做登入，避免發生遺憾

四、技術相關

• 程式碼風格：一樣米養百樣人，工程師來自五湖四海自然風格迥異，公司可以使用 ESLint 這類的工具來約束風格，但實際上程式碼的效能、長度、分類…很多事情還是需要有人說明過去的撰寫風格
• Deploy 的方式： 如果團隊有導入 CI/CD，你就要跟對方解釋清楚哪些 branch 會觸發對應的 server，如果 branch merge 時會自動 deploy 請小心謹慎
• 技術文件：種類繁多，大概可以分成：程式碼內部註解、api 功能說明文件、過去開發的 SPEC 這 3 種；基本上這些文件是為了讓對方能快速了解專案的結構而不是讓他了解每一行程式碼的意義。

五、工作相關

• 列出例行公事清單：像是很多公司都有跑 scrum sprint，你可以向新人說明例會時間點、參與人員、討論內容；藉此讓他快速進入開會討論時的狀況
• 列出手上待完成事項：新人會接替你的工作，你可以先將手中待完成的任務難易度排序，先將簡單的任務交給他，觀察他的完成度及適應性
• 提點行政庶務：每個新人在剛入職時誰都不認識，印表機不知道怎麼操作、專案管理系統不會用、電腦不會設定開發環境；你可以撰寫『秘笈』讓他了解遇到問題時可以向哪個窗口提問
• 了解合作團隊職權分類：以一個雲端團隊來說，你需要讓新人知道前端遇到問題要找誰、後端發生 bug 要問誰，整理好團隊裡面的聯絡窗口才能讓新人更快的融入團隊
• 保密協議：如果公司開發的專案有其機密性，記得提醒新進人員不可洩露專案內容出去。