如何編寫前端設計文檔？

在筆者所在的前端研發流程中, 【技術調研及方案設計】屬於連接【需求階段】和【開發階段】的中間節點。在需求詳評 (三審) 後了, 需求的功能和交互已經基本確定, 而在實際進入開發之前, 還有一些 待確定的技術要點需要補全, 這些要點包括:

• 需求的可實現性 (理論上能不能做, 是否能支持某個功能, 某個交互是否能實現, 實現功能的成本是否過於巨大), 假設你給 PM 拍胸口說啥功能你都能實現, 然後 Ta 提了一個這樣的需求 [1]...

• 需求的整體架構 (前後端交互的流程和方式, 接口的路徑、請求和響應參數)

• 需求的具體設計 (前端頁面 / 組件 / 服務的設計)

而編寫前端設計文檔就是補全和完善上述這些技術要點的過程以及過程沉澱出的產物.

爲什麼寫前端設計文檔?

Measure twice and cut once 三思而後行

如果所有產品的功能都是在頁面上展示 Hello, World 的話, 那麼我們大概是不需要設計文檔的，然而現實世界的產品需求功能充滿了複雜性, 一個頁面可能展示了非常多不同來源數據, 有不同的交互細節, 周密的業務流程, 這就要求我們需要在動手開發之前先想好這個功能能不能實現以及如何實現.

試想一下如果不寫設計文檔, 擼起袖子就開幹可能會有哪些 Bad Ending?

• Case 1: 需求要你接入一個第三方 SDK, 你和第三方的研發同學開了個小會對齊發現沒有啥問題, 你沒有做詳細的技術設計印證是否 SDK 能完整支持需求, 也沒有測試過 SDK, 結果開發到一半發現 SDK 的功能不能完整支持你的業務需求, 如果要支持必須得第三方排期支持, 而這個項目本來預計要儘快上線的, 你人傻了 (First Blood🙅）

• Case 2: 需求中的一個功能需要你同時請求多個接口, 你沒有充分考慮這些接口失敗的容災, 對這些請求的返回聽天由命, 結果上線後用戶在使用中經常遇到一個接口請求成功了, 另一個失敗了, 造成數據不一致, 用戶反饋功能不可用, 你人傻了 again (Double Kill!🙅)

• Case 3: 需求中需要開發一個彈窗, 你匆匆一瞥覺得這也就半天就能開發完, 結果沒有充分考慮到這個彈窗有五個模式三個形態八種流程, 低估了 2/3 的排期, 排期到了 QA 催促爲什麼還不提測, 匆匆做完測試之後出現了一堆 Bug, 你人傻了 one more time (Triple Kill!🙅)

我是三傻 · 史塔可嗎?

而設計前端文檔, 就是儘快能在開發之前將技術上不確定的點確定好, 將需求的設計方式提前構思好, 以減少後續開發出現風險和問題的可能性. 雖然技術文檔也不能 100% 預見或者評估出所有潛在的風險和問題, 但是技術文檔能在相當程度上減少這類風險.

除了通過設計文檔儘量避免上述的問題之外, 設計良好的前端文檔可以幫助你提升開發的質量和效率, 原因如下:

• 當你書寫設計文檔時就像是在構思文章的提綱, 一旦確定了代碼的整體架構和組件結構, 你就有了構建需求的藍圖, 而開發就是完成各種組成部分的細節, 這比邊幹邊想效率要高很多.

• 當你在設計時將代碼的架構、類型、接口定義好, 開發時甚至可以直接複用設計文檔中的代碼

• 而當你完成設計文檔以後, 組內同學或者其他合作方就可以瞭解你的設計, 幫助你判斷設計方案的優劣, 瞭解你方案中對相關方的需求和影響, 可以更高效率的對齊技術信息.

如何寫好前端設計文檔？

既然編寫設計文檔可以更好的幫助我們在開發前階段進行趨利和避害，那麼編寫設計文檔應該是一件很有必要的事情了, 在這個判斷下, 我們新的問題是: 如何寫好一篇設計文檔?

筆者認爲一篇合格的設計文檔應該滿足至少幾個條件

• 內容完備

• 設計文檔體現的是用你的大腦去完整執行一遍需求流程的模擬, 它必須包含這個需求涉及到的全部環節、狀態與環境, 你需要考慮到你的上下游和你的關係, 你如何請求服務或者別人如何使用你的服務, 你的頁面是在什麼環境下運行 (瀏覽器 / Webview/CEF), 以及這些相關環節如果出現問題對你的影響, 如果有一種情況被你疏忽了, 那可能都是線上問題或者是事故的禍根;

• 在設計你的頁面和功能時, 你應該把這個頁面或者組件的全部功能列舉清楚, 這些頁面或組件又有什麼樣的狀態變化和交互, 只有把這些方面考慮齊全了, 纔可能更客觀的評估工作量的多少.

• 此外, 在設計文檔中應該收集齊開發需要的各類文檔和資料, 以提升查找所需信息的效率, 例如筆者團隊前端設計的文檔模版中會收集如下內容

• 需求文檔

• 設計視覺稿

• 服務端 IDL

• 第三方服務 / SDK 文檔

• 測試 Case

• 埋點文檔

• 運營資源列表 (optional)

• 走查及驗收文檔

• 結構清晰: 合理且清晰的文檔組織能夠反映你良好的思考順序, 也便於他人理解, 筆者一般採用需求整體 - 頁面 - 組件 / 模塊這樣的層次去組織設計方案, 就像你在開發一個 React/Vue 頁面或組件, 也是先設計父組件, 再去思考組成它的子組件的功能 (根據具體情況也可以先設計底層模塊和服務), 就如庖丁解牛, 如果你能對整體結構和各個組成部分之間的結構和邊界界定清晰的話, 相信你的代碼模塊化也會做的更好.

• 便於執行: 一個理想的設計文檔應該可以做到讓別人來看你的文檔也知道怎麼實現需求 (這個標準確實有些理想), 但是如果一篇設計文檔寫完你還是對如何進行開發毫無頭緒或者存在疑點, 那麼這片設計文檔可能還不夠完善, 更好的設計文檔應該就像是樂高或者宜家的說明書一下, 看着文檔你就應該對如何操作了然於胸.

以上是一些關於設計文檔的理論描述, 下面讓我們關注一些更具體的細節

• 如果你要開發一個新應用

• 創建新的 Git 倉庫

• 項目初始化

• 項目部署流程

• 接入監控

• 如果你要開發一個新頁面

• 頁面的路由及相應的 query

• 頁面的整體功能與結構設計

• 如果你要開發一個組件, 你需要思考:

• 一個頁面其實和組件的設計有很多共同之處, 他們都有三個組成部分

• State: 有哪些狀態? 本地狀態或需要通過接口獲得的狀態?

• UI: 用戶界面由哪些部分組成? 狀態如何驅動 UI 的變化

• Logic: 有哪些邏輯? 這些邏輯可以被歸類爲若干類子邏輯 (操作數據、事件響應、調用服務), 這些邏輯會如何改變狀態, 又如何響應用戶的交互或者其他事件?

讓我們舉個🌰例子

以筆者遇到過的一個複雜需求爲例, 這個需求的內容接入用戶反饋的 SDK, 並且在反饋的後臺系統看到這個用戶的反饋和用戶信息, 我當時的設計過程是這樣的:

• 首先在閱讀完需求文檔後，我們瞭解到這個需求大致有兩部分組成

• (1) C 端需求: 在用戶客戶端 / App 裏的頁面增加客服彈窗的入口

• (2) B 端需求: 在客服後臺中, 當客服同學選擇某個用戶的會話時可以看到這個用戶的用戶信息 / 課程信息 / 訂單信息

• 讓我們在大腦中完整的跑一下從 C 端到 B 端的這個流程

• 用戶在 C 端提交反饋

• C 端的客服 SDK 識別這個用戶的身份信息, 連帶提交的反饋信息傳送到客服的數據庫中

• B 端的客服登錄以後能夠看到這個反饋信息, 並且能拿到這個用戶的身份信息

• B 端客服可以在選中這個反饋會話後繼續查看用戶的用戶信息、訂單信息 (學生) 或課程信息(老師)

• 最終用一張流程圖來概括就是

有了整體的流程結構, 讓我們來思考一下其中關鍵環節的細節

• 客服 SDK 如何識別 C 端用戶的身份信息?

• C 端用戶在登錄和不登錄時身份判斷的差異?

• B 端如何獲得反饋者的身份信息

• B 端的用戶信息 / 課程信息 / 訂單信息頁面如何實現? 是在客服平臺的工程開發還是使用 iframe?

• 如果是 iframe, 上面的三個頁面如何獲得反饋者的身份信息

• 經過和客服平臺的討論和設計後, 設計方案才能確定

在把技術流程和方案確定以後，我們要開始對功能的實現進行具體的設計

• C 端部分:

• 因爲各個頁面的彈窗按鈕樣式和功能一致, 我們需要設計一個彈窗按鈕組件

• 彈窗按鈕組件底層調用了客服 SDK, 所以底層需要設計一個客服彈窗服務模塊

• 在需要引入客服彈窗入口的頁面引入彈窗按鈕組件

• B 端部分

• 因爲決定在客服平臺植入一組 iframe 頁面, 所以需要單獨啓動一個獨立的倉庫, 需要進行一些配置工作

• 開發三個 iframe 頁面: 用戶信息 / 課程信息 / 訂單信息

• 當這些組成部分都清晰了, 我們纔可以動手設計具體細節

當走到這裏的時候, 需求的整體流程、前後端交互方式、以及具體功能實現可以說基本完成了, 這時候再開始動工就減少了技術上的不確定性, 開發思路也瞭然於胸中, 可謂是文思如泉湧，按鍵如有神⌨️

當然, 即使是到了這一步也不能說是思考的終點, 在開發、聯調、測試、部署中還是可能會有意外事情的發生, 但是隨着你設計思路和實踐的逐步完善，這種意外會相對減少，即使發生你也能遊刃有餘, 總能夠保證需求高質量、高效率的交付, 成爲團隊信賴的小夥伴👏

最後附上筆者團隊前端的設計文檔模版

1. 需求背景及資源

• 需求背景

• 相關文檔 & 資源

• 需求文檔:

• 設計視覺稿:

• 服務端 IDL:

• 第三方服務 / SDK 文檔

• 測試 Case:

• 埋點文檔:

• 運營資源列表 (optional):

• 走查及驗收文檔:

2. 排期

需求 Timeline

0twTKJ

排期拆分

cp9Gsi

3. 設計方案

整體方案

• 項目搭建

• 部署方案

• 監控方案

頁面設計

• 頁面描述

• URL

• UI & 交互邏輯 (UI 拆分)

• 狀態

• 請求邏輯

• 業務邏輯

• 埋點邏輯

組件設計

• 模塊描述

• UI & 交互邏輯

• 狀態 / Props

• 業務邏輯

• 埋點邏輯

公用模塊

• 模塊描述

• 業務邏輯

4.Todos

• 設計方案

• 開發

• 頁面 1

• 組件 1

• 通用模塊 1

• 聯調

• 測試

• UI 走查

• 上線

感謝你閱讀到這裏, 請注意這也只是筆者根據自身經驗提出的一些關於技術設計的建議, 也存在不少筆者未曾設想的方面和不完善之處, 請讀者也根據實際情況不斷完善設計實踐, 並和大家一起分享.

參考資料

[1] 這樣的需求: https://zhuanlan.zhihu.com/p/41305243

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/l2NTuyDahF6wXHE91MgT-A