# 你知道對專案來說，README.md 有多麼重要嗎？ ── 工程師血淚史

- 作者：林鼎淵（Dean Lin）
- 網址：https://deanlin.net/blog/202208/why-readme-matters/
- 發布：2022-08-05
- 主題：團隊合作
- 系列：工程師血淚史
- 標籤：README、Documentation、Project Management、技術文件、文件
- 摘要：如果公司的專案很多，README.md 又沒有寫好，那後續接手的人會非常痛苦；如果公司專案的規模很大，README.md 又缺乏維護，那這個專案已經半隻腳踏進棺材。

如果公司的專案很多，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

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

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

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

  IMG from：[https://commons.wikimedia.org/](https://commons.wikimedia.org/)

### 使用者操作手冊 ── User Manual

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

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

### Demo 影片── Demo Video

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

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

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

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

### Function map

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

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

> [GitMind](https://gitmind.com/) 是個不錯的工具，推薦大家使用看看。

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

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

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

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

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

```

---

關於作者：林鼎淵（Dean Lin），台灣的生成式 AI 企業內訓講師、外商資安公司軟體專家，也是生成式 AI 創新學院發起人。出版 7 本書（包含全台第一本 ChatGPT 應用專書），兩度獲得 iThome 鐵人賽佳作，累積上百場授課與顧問經驗。（https://deanlin.net/about/）
引用時請附上原文網址：https://deanlin.net/blog/202208/why-readme-matters/