Introduction
已經在 Hahow 工作了一段時間，在這段期間中，除了持續精進程式設計之外，還逐漸學習了一項新技能：編寫前期規劃的技術文件。
並不是每個開發團隊在開始開發之前都會進行這個步驟，但我認為這是一個相當不錯的流程。
通過一份文件，開發團隊可以迅速對齊對功能實現的方向和預期要完成的任務，這樣可以避免走錯大方向，而在 Code Review 階段也能省下許多討論時間。
寫這篇文章的目的是為了記錄一下這種技術文件通常會包含哪些內容，並分享一些我的見解。
我認為一份完整的技術文件通常會包括以下幾個部分：
- Title
- Metadata
- Changelog(optional)
- Glossory(optional)
- Solutions
- Q&A or Discussions
- Missions
以下就來介紹一下他們：
Title
標題是大家能否快速找到文件的關鍵，格式通常如下：
1 | [團隊名稱] <這份文件的功能>技術文件 |
在 <這份文件的功能> 這個部分，應該包含大家可能會用來搜索的關鍵字，比方說實體活動的功能，有時候會被簡稱為 O2O，那標題應該命名為 企業活動（O2O）技術文件
Metadata
這裡簡單列出文件的基本資訊，有點像打開電腦資料夾後，檢視檔案清單的那些選項。具體要列出哪些內容，可以根據團隊的需求進行調整，但通常至少應該包含作者的名字，以我們團隊來說通常會包括下面這些項目：
- Authors
- Team
- Reviewers
- Created at
- Links(Tickets link, Design Draft link, frontend doc link… etc)
Changelog
這部分通常以表格形式呈現。有時，一個功能可能需要時隔相當長一段時間後再次開發，透過 Changelog，我們可以了解哪些部分是之前的人寫的，哪些是新添加的。
但如果功能較小，或者有其他理由認為不需要這些資訊，則可以選擇省略這一部分。
以下是一個範例：
| Date | Description |
|---|---|
| 2023/1/19 | 起草 |
| 2023/2/23 | 新增搬遷 RDS 計畫 |
Glossory
有時在規劃一個大家不太熟悉的功能時，需要有一個類似辭典的段落，以便讓團隊成員熟悉一些必要的專業術語，然後再繼續閱讀。
除此之外，使用中文名詞溝通的時候，有時會遇到每個人對於這個中文名詞指涉的內容的想法都不一樣的情況，也可以透過這個段落拉齊大家的名詞共識。
以下是一個範例：
| Terms | Description |
|---|---|
| Kubernetes | 又簡稱 K8S，是用來管理 container 的叢集管理工具 |
| Pod | 是 K8S 中可部署的最小單元，一個 pod 裡面可以有多個 container |
Solutions
這是技術文件中最核心的部分，也就是這個功能在你的規劃中如何實現。
但每個人的想法 / 風格不盡相同，每次開發的功能可能也都大相徑庭，所以沒有一個通用的模板可以參考。
但根據個人經驗，在撰寫時可以盡量包含下面這些面向：
- What: 這個功能要解決什麼問題？
- Why: 為什麼這樣設計？有沒有什麼背景是團隊需要了解的？或者大家可能會問的問題也可以補充上去。
- When: 有些功能具有時間性，像是 phase1 / phase2，有這類資訊的話也可以補充上去
- Where: 這個功能是放在哪裡？建議可以放在段落標題表示，ex.
[後台] 權限列表 - Who: 這個段落是寫給誰看的？以後端來說，API 相關資訊需要前後端都知道，但實作細節只有後端工程師需要確認，建議可以放在段落的標題表示，ex.
## [For 後端] Schema Change - How: 如何執行？最最最核心的部分，像是 API 的設計 / 想像的 Pseudo code / 實作步驟等等，如果可以用圖片說明的話，建議作圖進一步幫助大家加速理解
另外有些解決方案可能會想到多種，也可以都寫出來給大家討論
如何發想
剛開始寫規劃文件的時候，我覺得最難的部分是決定從哪裡著手。經過一段時間的嘗試後，我算是找到了一套適合自己的工作流程。
首先，我會仔細審閱規格和設計稿，同時記錄下所有我認為程式中需要調整的地方。對於後端來說，這通常意味著確定前端可能需要哪些 API
在列出所有需要調整的項目之後，我會思考為了完成這些 API 或整個功能，還需要完成哪些其他任務。這可能包括資料庫架構改變，或者是否需要設定定期執行的程式。
除了這些直接相關的任務之外，還有一些完全沒有畫面可以參考的任務，比如將應用程式容器化。對於這類任務，從終點回推對我來說是一個不錯的策略。舉例來說，如果最終目標是將應用程式部署在 EKS 上，那麼在這之前我就必須先有一個 EKS cluster。但在建立 cluster 之前，我需要先設定網路基礎架構。而要在 K8S 中部署容器，當然我需要先準備好 Dockerfile。通過這種方式，就可以把不足的部分慢慢補齊。
Q&A or Discussions
這個部分有點像 Solutions 裡面的 Why，但也可以單獨成為一個段落。
在這裡，你可以列出自己想到的一些問題 / 疑慮，這裡也可以是提供團隊提問的空間。這樣做有助於刺激思考，讓文件更加完善，從而避免個人盲區。
Missions
最後一部分是將所有需要實現的細節拆分成一個個具體的任務。任務越細越好，這樣在規劃排程時會更準確。此外，這樣做還能提高 Code Review 的品質。
| 編號 | 任務 | 任務說明 | 估點 | ticket link |
|---|---|---|---|---|
| 1 | Routing 建立 | … | 1 | … |
| 1 | 基礎建設 | … | 2 | … |
Conclusion
我自認為我目前還不是可以迅速且熟練地撰寫技術文件的人。我正在努力拿捏文件中需要描述到多少細節，又有哪些部分可以交給實作者自己去思考。
若將每一個細節都思考透徹，很容易花費過多的時間在規劃階段，時間上甚至可能跟自己發個 PR 的時間差不多。
另一方面，在撰寫規劃文件的過程中，我們不可能事先想到所有的細節和可能會遇到的問題。難免會有一些在規劃階段沒有預見到的任務，在實作過程中才會浮現出來。面對這樣的情況，我們能做的只有盡最大努力去想到所有可能的情況，並且嘗試把可能遺漏的部分補充完整。
總結來說，我自己滿推薦開發團隊在實作前撰寫規劃技術文件。它可以幫助團隊快速的達成共識，並進行有效率的溝通，還可以留存當下的情境，作為未來當程式碼變得難以理解時的一個參考依據。從各個面向來看，都為開發過程帶來了很大的效益。
