如何編寫前端設計文檔
時間：2023-10-07 14:36:01 | 來源：網站運營
時間：2023-10-07 14:36:01 來源：網站運營
如何編寫前端設計文檔：
前端設計文檔是什么?
- 在筆者所在的前端研發(fā)流程中, 【技術調研及方案設計】屬于連接【需求階段】和【開發(fā)階段】的中間節(jié)點。在需求詳評(三審)后了, 需求的功能和交互已經基本確定, 而在實際進入開發(fā)之前, 還有一些待確定的技術要點需要補全, 這些要點包括
- 需求的可實現(xiàn)性(理論上能不能做, 是否能支持某個功能, 某個交互是否能實現(xiàn), 實現(xiàn)功能的成本是否過于巨大),假設你給 PM 拍胸口說啥功能你都能實現(xiàn), 然后 Ta 提了一個這樣的需求...
- 需求的整體架構(前后端交互的流程和方式, 接口的路徑、請求和響應參數(shù))
- 需求的具體設計(前端頁面/組件/服務的設計)
- 而編寫前端設計文檔就是補全和完善上述這些技術要點的過程以及過程沉淀出的產物.
為什么寫前端設計文檔?
Measure twiceandcut once三思而后行
- 如果所有產品的功能都是在頁面上展示 Hello, World 的話, 那么我們大概是不需要設計文檔的，然而現(xiàn)實世界的產品需求功能充滿了復雜性, 一個頁面可能展示了非常多不同來源數(shù)據(jù), 有不同的交互細節(jié), 周密的業(yè)務流程, 這就要求我們需要在動手開發(fā)之前先想好這個功能能不能實現(xiàn)以及如何實現(xiàn).
- 試想一下如果不寫設計文檔, 擼起袖子就開干可能會有哪些 Bad Ending?
- Case 1: 需求要你接入一個第三方 SDK, 你和第三方的研發(fā)同學開了個小會對齊發(fā)現(xiàn)沒有啥問題, 你沒有做詳細的技術設計印證是否 SDK 能完整支持需求, 也沒有測試過 SDK, 結果開發(fā)到一半發(fā)現(xiàn) SDK 的功能不能完整支持你的業(yè)務需求, 如果要支持必須得第三方排期支持, 而這個項目本來預計要盡快上線的, 你人傻了 (First Blood ）
- Case 2: 需求中的一個功能需要你同時請求多個接口, 你沒有充分考慮這些接口失敗的容災, 對這些請求的返回聽天由命, 結果上線后用戶在使用中經常遇到一個接口請求成功了, 另一個失敗了,造成數(shù)據(jù)不一致, 用戶反饋功能不可用, 你人傻了 again (Double Kill! )
- Case 3: 需求中需要開發(fā)一個彈窗, 你匆匆一瞥覺得這也就半天就能開發(fā)完, 結果沒有充分考慮到這個彈窗有五個模式三個形態(tài)八種流程, 低估了 2/3 的排期, 排期到了 QA 催促為什么還不提測, 匆匆做完測試之后出現(xiàn)了一堆 Bug, 你人傻了 one more time (Triple Kill! )
我是三傻·史塔可嗎?
- 而設計前端文檔, 就是盡快能在開發(fā)之前將技術上不確定的點確定好, 將需求的設計方式提前構思好, 以減少后續(xù)開發(fā)出現(xiàn)風險和問題的可能性.雖然技術文檔也不能 100%預見或者評估出所有潛在的風險和問題, 但是技術文檔能在相當程度上減少這類風險.
- 除了通過設計文檔盡量避免上述的問題之外, 設計良好的前端文檔可以幫助你提升開發(fā)的質量和效率, 原因如下
- 當你書寫設計文檔時就像是在構思文章的提綱, 一旦確定了代碼的整體架構和組件結構, 你就有了構建需求的藍圖, 而開發(fā)就是完成各種組成部分的細節(jié), 這比邊干邊想效率要高很多.
- 當你在設計時將代碼的架構、類型、接口定義好, 開發(fā)時甚至可以直接復用設計文檔中的代碼
- 而當你完成設計文檔以后, 組內同學或者其他合作方就可以了解你的設計, 幫助你判斷設計方案的優(yōu)劣, 了解你方案中對相關方的需求和影響, 可以更高效率的對齊技術信息.
如何寫好前端設計文檔？
- 既然編寫設計文檔可以更好的幫助我們在開發(fā)前階段進行趨利和避害，那么編寫設計文檔應該是一件很有必要的事情了, 在這個判斷下, 我們新的問題是: 如何寫好一篇設計文檔?
- 筆者認為一篇合格的設計文檔應該滿足至少幾個條件
- 內容完備
- 設計文檔體現(xiàn)的是用你的大腦去完整執(zhí)行一遍需求流程的模擬, 它必須包含這個需求涉及到的全部環(huán)節(jié)、狀態(tài)與環(huán)境, 你需要考慮到你的上下游和你的關系, 你如何請求服務或者別人如何使用你的服務, 你的頁面是在什么環(huán)境下運行(瀏覽器/Webview/CEF), 以及這些相關環(huán)節(jié)如果出現(xiàn)問題對你的影響, 如果有一種情況被你疏忽了, 那可能都是線上問題或者是事故的禍根;
- 在設計你的頁面和功能時, 你應該把這個頁面或者組件的全部功能列舉清楚, 這些頁面或組件又有什么樣的狀態(tài)變化和交互, 只有把這些方面考慮齊全了, 才可能更客觀的評估工作量的多少.
- 此外, 在設計文檔中應該收集齊開發(fā)需要的各類文檔和資料, 以提升查找所需信息的效率, 例如筆者團隊前端設計的文檔模版中會收集如下內容
- 需求文檔
- 設計視覺稿
- 服務端 IDL
- 第三方服務/SDK 文檔
- 測試 Case
- 埋點文檔
- 運營資源列表(optional)
- 走查及驗收文檔
- 結構清晰: 合理且清晰的文檔組織能夠反映你良好的思考順序, 也便于他人理解, 筆者一般采用需求整體 - 頁面 - 組件/模塊這樣的層次去組織設計方案, 就像你在開發(fā)一個 React/Vue 頁面或組件, 也是先設計父組件, 再去思考組成它的子組件的功能(根據(jù)具體情況也可以先設計底層模塊和服務), 就如庖丁解牛, 如果你能對整體結構和各個組成部分之間的結構和邊界界定清晰的話, 相信你的代碼模塊化也會做的更好.
- 便于執(zhí)行: 一個理想的設計文檔應該可以做到讓別人來看你的文檔也知道怎么實現(xiàn)需求(這個標準確實有些理想), 但是如果一篇設計文檔寫完你還是對如何進行開發(fā)毫無頭緒或者存在疑點, 那么這片設計文檔可能還不夠完善, 更好的設計文檔應該就像是樂高或者宜家的說明書一下, 看著文檔你就應該對如何操作了然于胸.
- 以上是一些關于設計文檔的理論描述, 下面讓我們關注一些更具體的細節(jié)
- 如果你要開發(fā)一個新應用
- 創(chuàng)建新的 Git 倉庫
- 項目初始化
- 項目部署流程
- 接入監(jiān)控
- 如果你要開發(fā)一個新頁面
- 頁面的路由及相應的 query
- 頁面的整體功能與結構設計
- 如果你要開發(fā)一個組件, 你需要思考:
- 一個頁面其實和組件的設計有很多共同之處, 他們都有三個組成部分
- State: 有哪些狀態(tài)? 本地狀態(tài)或需要通過接口獲得的狀態(tài)?
- UI: 用戶界面由哪些部分組成? 狀態(tài)如何驅動 UI 的變化
- Logic: 有哪些邏輯? 這些邏輯可以被歸類為若干類子邏輯(操作數(shù)據(jù)、事件響應、調用服務), 這些邏輯會如何改變狀態(tài), 又如何響應用戶的交互或者其他事件?
讓我們舉個 例子
以筆者遇到過的一個復雜需求為例, 這個需求的內容接入用戶反饋的 SDK, 并且在反饋的后臺系統(tǒng)看到這個用戶的反饋和用戶信息, 我當時的設計過程是這樣的:
- 首先在閱讀完需求文檔后，我們了解到這個需求大致有兩部分組成
- (1) C 端需求: 在用戶客戶端/App 里的頁面增加客服彈窗的入口
- (2) B 端需求: 在客服后臺中, 當客服同學選擇某個用戶的會話時可以看到這個用戶的用戶信息/課程信息/訂單信息
- 讓我們在大腦中完整的跑一下從 C 端到 B 端的這個流程
- 用戶在 C 端提交反饋
- C 端的客服SDK識別這個用戶的身份信息, 連帶提交的反饋信息傳送到客服的數(shù)據(jù)庫中
- B 端的客服登錄以后能夠看到這個反饋信息, 并且能拿到這個用戶的身份信息
- B 端客服可以在選中這個反饋會話后繼續(xù)查看用戶的用戶信息、訂單信息(學生)或課程信息(老師)
- 最終用一張流程圖來概括就是
- 有了整體的流程結構, 讓我們來思考一下其中關鍵環(huán)節(jié)的細節(jié)
- 客服SDK如何識別 C 端用戶的身份信息?
- C 端用戶在登錄和不登錄時身份判斷的差異?
- B 端如何獲得反饋者的身份信息
- B 端的用戶信息/課程信息/訂單信息頁面如何實現(xiàn)? 是在客服平臺的工程開發(fā)還是使用 iframe?
- 如果是 iframe, 上面的三個頁面如何獲得反饋者的身份信息
- 經過和客服平臺的討論和設計后, 設計方案才能確定
- 在把技術流程和方案確定以后，我們要開始對功能的實現(xiàn)進行具體的設計
- C 端部分:
- 因為各個頁面的彈窗按鈕樣式和功能一致, 我們需要設計一個彈窗按鈕組件
- 彈窗按鈕組件底層調用了客服 SDK, 所以底層需要設計一個客服彈窗服務模塊
- 在需要引入客服彈窗入口的頁面引入彈窗按鈕組件
- B 端部分
- 因為決定在客服平臺植入一組 iframe 頁面, 所以需要單獨啟動一個獨立的倉庫, 需要進行一些配置工作
- 開發(fā)三個 iframe 頁面: 用戶信息 / 課程信息 / 訂單信息
- 當這些組成部分都清晰了, 我們才可以動手設計具體細節(jié)
- 當走到這里的時候, 需求的整體流程、前后端交互方式、以及具體功能實現(xiàn)可以說基本完成了, 這時候再開始動工就減少了技術上的不確定性, 開發(fā)思路也了然于胸中, 可謂是文思如泉涌，按鍵如有神 ??
- 當然, 即使是到了這一步也不能說是思考的終點, 在開發(fā)、聯(lián)調、測試、部署中還是可能會有意外事情的發(fā)生, 但是隨著你設計思路和實踐的逐步完善，這種意外會相對減少，即使發(fā)生你也能游刃有余, 總能夠保證需求高質量、高效率的交付, 成為團隊信賴的小伙伴
最后附上筆者團隊前端的設計文檔模版
1.需求背景及資源
- 需求背景
- 相關文檔 & 資源
- 需求文檔:
- 設計視覺稿:
- 服務端 IDL:
- 第三方服務/SDK 文檔
- 測試 Case:
- 埋點文檔:
- 運營資源列表(optional):
- 走查及驗收文檔:
2.排期
3.設計方案
- 頁面設計
- 頁面描述
- URL
- UI & 交互邏輯(UI 拆分)
- 狀態(tài)
- 請求邏輯
- 業(yè)務邏輯
- 埋點邏輯
- 組件設計
- 模塊描述
- UI & 交互邏輯
- 狀態(tài) / Props
- 業(yè)務邏輯
- 埋點邏輯
4.Todos
感謝你閱讀到這里, 請注意這也只是筆者根據(jù)自身經驗提出的一些關于技術設計的建議, 也存在不少筆者未曾設想的方面和不完善之處, 請讀者也根據(jù)實際情況不斷完善設計實踐, 并和大家一起分享.
在線咨詢
