隨著專案迭代，除了程式碼越來越龐大外，資料夾結構也越來越複雜。

到後來，可能連開發人員自己都搞不清楚每個資料夾在做什麼事。

為了避免交接、教育訓練時要花很多時間回憶、解釋，我們應該把這些資訊記錄到文件中。

這邊推薦一個直接產生資料夾結構的套件「tree」，透過簡單的指令就能生成樹狀的目錄結構，以此加速文件撰寫。

安裝 tree 套件

在 Windows & Mac 有安裝 npm 的電腦上，只要輸入如下指令便可安裝。

npm install -g tree-cli

安裝好後，可透過 tree -h 查看有哪些指令可以使用。

官方文件中有提醒，Windows 要用「treee」來當指令（多一個 e），筆者的環境為 Mac。

使用 tree 生成樹狀的目錄結構

下面分享幾個高頻率使用的指令：

• tree : 顯示「資料夾」與「目錄」

• tree -d : 僅顯示「資料夾」

• tree -l n : 顯示到第 n 層目錄（tree -l 2 就是顯示兩層目錄）

• tree –ignore pattern : 排除不要顯示的檔案/資料夾（tree –ignore node_modules 就能排除 node_modules 資料夾）

• tree -o filename : 將結果寫入 filename 這個檔案

這邊展示一個組合指令： tree –ignore node_modules -l 3 -d > README.md

這個指令能將 3 層目錄資料夾（排除 node_modules）結果寫入 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

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

使用者操作手冊 ── 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 有多麼重要嗎？(本篇)