如果公司的專案很多，README.md 又沒有寫好，那後續接手的人會非常痛苦；如果公司專案的規模很大，README.md 又缺乏維護，那這個專案已經半隻腳踏進棺材。
身為工程師，我理解大部分的人都想把精力放在寫出更好的程式，但專案能否長期發展，其實是取決於「文件」；如果文件亂七八糟，或者甚至根本沒有制式文件，那這個專案的未來發展性堪憂。
從管理的角度來說，我們要去思考：「如果負責專案的工程師明天就不在了，這個專案能否進行下去？」
大綱一、為什麼 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
以後端來說，涉及機密、隱私、個人化的參數會需要自己填寫，比如：
- DB 帳號密碼、IP、Port
- JWT 有效期限
- Mail 相關參數
- Storage 路徑
➤ 在 Local 端的安裝＆運行步驟 ── Build Setup (Local)
是那種「複製貼上」就能夠順利安裝的步驟，可以放一些參考連結，但不要讓使用者需要去閱讀官方文檔才知道怎麼安裝。
以後端舉例，指令需至少包含如下內容：
- 專案安裝步驟
- DB Migration
- DB Seeder
- 運行專案
如果採前後端分離，可以附上 POSTMAN 的 collection 方便前端驗證。
➤ 在 Server 端的安裝＆驗證步驟 ── Build Setup (Server)
如果不是採取自動部署的策略，那筆者建議紀錄如下內容：
- 專案運行所需套件，及其對應的指令
- 伺服器端參數（ex：API 最長可執行時間、可上傳檔案容量限制、單個 IP 每分鐘存取次數）
- 不同環境對應的 Server ip
- 相關參數調整後，重啟使其生效的指令
- 部署完成後，可以透過什麼方式（工具）驗證功能皆如預期運行
➤ 可提供支援的同仁 ── Support
讓初次接觸專案的人知道遇到問題可以找誰詢問，建議在這個部分放上開發人員的聯絡方式（ex：座位、email）。
有時問題可能有其歷史背景，所以可以用附註形式，放上了解這份專案歷史的同仁（ex：主管、負責的 PM）。
➤ 注意事項 ── Warning
每個專案或多或少都會有一些特別的設計，時間拉長難免遺忘，建議把他們記錄下來，比如：
- 如果 API 文檔是用指令產生的，請記得記錄下來
- 如果有設計排程（Schedule），把觸發的時間點列出
- 前端在不同環境的建立指令（Script）
- 如果用到特別的套件，建議簡單說明在什麼時機應用，並放上官方文檔連結
- 專案的授權條款（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 有多麼重要嗎？(本篇)▶︎ 如果這篇文章有幫助到你1. 可以點擊下方「Follow」來追蹤我～
2. 可以對文章拍手讓我知道 👏🏻你們的追蹤與鼓勵是我繼續寫作的動力 🙏🏼▶︎ 如果你對工程師的職涯感到迷茫1. 也許我在iT邦幫忙發表的系列文可以給你不一樣的觀點 💡
2. 也歡迎您到書局選購支持，透過豐富的案例來重新檢視自己的職涯
