如何寫一份前端的開發設計文件？
軟體設計文件 (Software Design Document)，在軟體開發的領域來說，大家都知道是不可或缺的東西，但常常礙於現實(時程、團隊…等等)，也會很難做到的一件事。
尤其前端的開發者，在很多組織與團隊中，相信並不是所有前端都會把這件事情視為很重要的一件事，很多人其實也不知道如何寫一份好的設計文件，當然包含我自己也不確定什麼樣是一份”好的”前端開發設計文件。
常常也會跟其他公司、或是其他團隊的前端朋友討論，前端的設計文件應該包含什麼，我們都覺得根據不同的團隊與組織，絕對會有不一樣的情境與不一樣的內容。因此這篇想記錄一下，在一開始跟著團隊開發、不斷地調整屬於我們自己的前端開發設計文件，到現在統整出來「可能適合」我們團隊的前端開發文件是什麼樣子。
為什麼需要開發設計文件？
不論在哪一個軟體開發領域，開發的設計文件絕對是很需要的。
嘗試想一下：如果你的設計方向其實不太對，等你開發完，發了一個 code review 的 request 之後，結果資深的 reviewer 跟你說這個不行要打掉重來，實務上真的有這麼多開發時間可以重頭來好幾次嗎？
我自己認為，開發設計文件可以避免設計方向的錯誤，減少在 code review 被大改的機率，也可以減少 reviewer 的 effort。
當然，前端的開發也是一樣的。
前端開發設計文件使用時機？
這份文件應該在何時被使用呢？
以我們團隊為例，我們會要求每一個前端開發者(當然後端或是測試的開發者也都需要先寫相對應的文件)，在收到一個 feature/ change，釐清完需求且 UX 差不多完成後，就必須要撰寫一份開發文件，這份開發文件必須經由團隊成員 review 過，不論是舉辦一場 design review、或是線上 offline 大家自己看完留言，確認這個 design 內容沒問題後，才能開始去實作。
有什麼例外嗎？
有，如果任何改動都要寫一份文件，可能也是沒這麼多時間。
所以如果是小型的 bugfix，或是改動不大，只是改改顯示文字、改 URL Link 這種不會動到 UI Flow 的小改動，就不需要寫成一份文件，只需要在 Pull Request 的時候寫清楚即可。因此，在 Pull Request 的 template 也會定義清楚每一個改動，你的描述需要包含些什麼。
前端的開發設計文件應該包含什麼？
在提到前端開發的設計文件需要包含什麼之前，要再次說一下，以下並不代表所以組織、團隊都適用，不同的組織或是團隊必須要討論出一份適合你們的前端開發設計文件。
以我們團隊為例，前端開發設計文件會包含：
- Overview
- UX Design
- Change Scope
- Component Design
- UI Flow
- State Design
- Detail Implementation
- Data Selector Design
- Frontend Test Design
- API Document Link
Overview
在文件的一開始，必須描述清楚這個改動的原因、以及目標想要達成的 Expected Result，並且附上改動的 Ticket 在這個章節裡面。
UX Design
接著，UX design 絕對是很重要的一部分，可以利用截圖 Figma 上面的設計圖，搭配簡單的文字敘述，讓其他團隊成員能夠視覺化的知道 UI 畫面會怎麼樣的改動，並且附上 Figma 的連結。
舉例來說：
Change Scope
在這個 Section，主要是要以開發者的角度，消化 Spec 之後，轉化成實際程式裡面要改動什麼。在這裡，我們通常會使用表格，條列式這次這個 feature 所有可能的改動，並且簡述現在的邏輯/設計，與改變後的邏輯/ 設計。
舉例來說：
改動中包含我們要把本來拿資料的方式，從一隻 API 變成從兩隻 APIs 來，我們就會這樣在文件中描述：
Component Design
如果這次的改動有包含更動本來的元件，或是新增新的元件，通常可以在這個 Section 用圖示的方法，來表示元件的階層關係。
舉例來說：
透過圖示的方式，讓閱讀的人知道，最外層是 <ContainerComponent/>，中間有一層 <LoginSection/> ，裏面才是實際要呈現的元素。在這階段就可以先透過這個 Component Desgin，在 review 階段就先找出不合理的元件階層設計，甚至是每一個元件的命名，都可以在 review 階段都決定以及討論好。
UI Flow
UI Flow 在設計文件中，也是一個很重要的環節，在這個 Scetion，可以讓閱讀的人了解到，這次改動的 UI Flow 是怎麼進行的，包含在哪個時間點 Call API、拿到資料後經過什麼條件判斷、更新哪些 state，最後改變了什麼 UI 長相。
舉例來說，流程圖會分為四個區塊：
- User Action: 使用者在介面上的操作，進入頁面、按下按鈕等等
- UI Display: 實際介面上呈現的東西
- UI Action: 頁面處理的邏輯，改變狀態或是經過什麼條件
- API Action: 實際呼叫了什麼 API
State Design
根據剛剛的流程圖，也必須要描述一下這次的改動新增了什麼 state，或是修改了哪個本來的 state。
舉例來說：
我們通常會描述 state name、這個狀態的 type 以及 default value，還會標注一下這是新加入的還是修改本來的狀態，而 locate 會視狀態多不多，比較多的話就會根據不同位置寫不同的表格，比較容易閱讀。如果是修改現有的狀態，也會建議在 Notes 寫一下為什麼要修改現有的狀態。
Detail Implementation
在設計文件中，我們也會有一個 detail implementation 的 section，這裡就不會特別要求要寫什麼，主要是希望如果有什麼比較特殊或是複雜的邏輯處理，可以先寫在這裡讓大家 review，避免到最後 code review 的時候才出現，會拉長 review 時間或是在當下才會增加很多討論。
我自己習慣會在這個 section 就盡量把我要改動的地方跟邏輯都寫上來，甚至一些 function 打算怎麼寫都會列在這裡，有時候就會直接把 code 都寫出來，一方面是提早讓團隊一起討論，另一方面也是趁這個機會整理一下思緒，想清楚再開始去實作。
Data Selector Design
除了上述實作的部分，我們團隊也有 UI Automation Test，因此也會有一個 Section 先針對這次改動會新增、或是改變的 data selector 列在這裡，給我們的 QA/SDET member 先做 review，如果有缺少，或是希望改用法或更名的，他們也都會在這時候提出來。
data selector 的用處：讓 UI Automation Test 能夠定義抓到需要的 DOM 元素
因為 QA/SDET member 通常不會一起 review 前端的 code change，為了避免到了最後都已經要 merge code ，且準備測試的時候才發現這些 data selector 不符合實際使用，就又要再有一個新的改動專門來調整，提早 review 就可以在實作的時候加入合適的 data selector。
舉例來說：
Frontend Test Design
最後也會針對這次改動，你預計要寫的測試內容，用條列式先列出來，讓團隊 review 有沒有缺少，或是不必要的測試。
API Document Link
文件內也需要附上相對應的 API 文件以供參考，如果 API 文件還沒完成，也可以先附上未來可能的連結。
可能很多人會有疑問，哪有這麼多時間可以寫這麼多內容？
實務上我們會把 design 跟 implementation 視為一樣重要，因此會在 planning 的時候就會留給你足夠的 design 時間，甚至 design 與 implementation 時間一樣都沒有關係，因為如果一個不好、或是不適合團隊的設計，就算你開發的再快，最後只會留下很多技術債、或是隱藏的問題，其實反而會產生更多成本，一開始就好好設計與討論才會更有效率。
另一個問題，就是往往設計結束後，實作又是一回事，文件很容易就 out of date 了，關於這點的話，我們會盡量在實作的時候有什麼根本來設計不太一樣的地方(命名或是流程)，就再回去調整文件，預期開發完成後，你本來的設計文件就可以轉化成這個改動的詳細文件。實務上會因為時程或是等等因素，這點不是很容易做到，不過會是一個比較理想的方向。另外就是，理論上不太會再去大改動流程，不然先前的 review 意義就降低了。
以上會是我們團隊的做法，不一定適用於每一個組織與團隊，但前端開發的設計文件絕對在開發週期中是很重要的一環，每個團隊都應該要討論出適合你們的設計文件應該包含的內容。
比起寫得快，想清楚再寫比較重要。
如果你覺得這篇文章對你有幫助，歡迎買杯咖啡贊助 ☕️ 謝謝
