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

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

大綱
一、為什麼 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 有多麼重要嗎？(本篇)

大綱
ㄧ、別談技術，先來看看筆者發生的蠢事
二、也許不是關關難過，而是從沒看過
三、如果方向是錯的，那離目標會越來越遠
四、總結

ㄧ、別談技術，先來看看筆者發生的蠢事

筆者過去購買家電時有個壞習慣，就是幾乎不看說明書；總覺得憑藉自己的理工頭腦可以輕鬆駕馭這些產品。

儘管大多數的狀況下我都能無師自通，但現實生活總是會找機會賞你幾個巴掌，有時我沾沾自喜的用法，過一段時間才發現根本是錯誤的。

就拿吸塵器來舉例好了，現代的吸塵器往往是多功能的，吸地、吸床單、吸鍵盤各有不同的吸頭；自以為聰明的我，認為吸附面積最大的頭一定是拿來吸地板的，但用了一陣子後總覺得馬力不夠，地板上常常有灰塵很難吸起來。

此時我去看說明書才明白，原來我一直拿吸床單的頭來吸地板！？儘管這樣也能使用，但卻無法發揮出每個吸頭應有的功效。

會發生這個蠢事，就是因為我覺得這個東西很簡單，沒必要看說明書。

二、也許不是關關難過，而是從沒看過

現在的技術日新月異，很多時候開發人員真的沒時間慢慢看文檔。

如果今天的需求較為簡單，那可能用套件的範例程式就能解決；但萬一需求較為複雜，那勢必要更深入的研究套件。

理論上是這麼說，但實際上有不少工程師，是選擇投入大量精力在魔改基礎的範例程式，而非去深入閱讀官方文檔。

就拿前端（Vue.js）來舉例，框架提供的 Component 有很多的 Props 可以使用；但很多人會選擇自己用 watch、computed 刻出一樣的功能。

一個問題往往有多種解決方案，但站在筆者的角度，除非框架沒有提供 Solution，不然盡量不要自己手刻，這些多餘的程式碼會導致日後的維護更加困難。

遇到需求請先閱讀官方文檔，很多時候有更省力的解決方案。

三、如果方向是錯的，那離目標會越來越遠

如果你人在台中，接下來打算前往台南；但車子卻一直往北開，你認為什麼時候才會抵達目的地？

前兩個案例，我們只是在解決問題的路上多花一點力氣；但在這個案例，是整個團隊白費力氣。

幾年前筆者曾選擇 Adonis.js 這個 Node.js 的框架來開發後端，前期開發的很順利，但隨著專案結構越來越複雜，我們發現這個框架缺少許多實用的功能，甚至還遇到不少需要等待作者維修的 Bug。

儘管當時已經使用它開發了 3 個月，但最終開發團隊還是決定忍痛放棄，跳槽到其他穩定的框架；而這次的失誤，導致系統架構要重新設計，不少程式需要重新撰寫。

會發生這個慘劇，是因為貿然選擇了一個不夠成熟的框架，且事前評估不足就直接投入開發。

四、總結

古人是因為缺少前人的經驗，才需要靠自己試錯來尋找答案。

現在資訊這麼發達，大部分的坑都有前輩幫你踩過了，沒必要親自去體驗。

儘管讀文檔要花費不少時間，但在很多時候它可以幫你解省更多時間。

磨刀不誤砍柴工，古人的話別當耳邊風。