iT邦幫忙

2025 iThome 鐵人賽

DAY 19
0
Build on AWS

AWS架構師的自我修養:30天雲端系統思維實戰指南系列 第 25

Day 13-0 | 跨團隊協作設計:技術文件、OpenAPI、共用契約 : API 文檔化與團隊協作標準建立 - 前言: 商業邏輯的素描

  • 分享至 

  • xImage
  •  

首先,先讓我們一同恭喜 我們終於走過了漫漫各種需求與技術的討論( a.k.a 混和雙打) 終於來到了實作了。


產品發想與機會探索=>需求定義與優先排序=>產品設計與使用者體驗=>技術規劃與系統設計=>(current)軟體開發與持續整合=>...

今天的內容會比較偏不同團隊間的合作依據與媒介文件,這是一個非常重要的議題。我不確定是不是每個人都有玩過一個遊戲叫做「傳聲話筒」,但簡單來說就是由一個起點在收到訊息之後不斷的經由下一個人將一開始的概念向下傳遞下去直至終點的遊戲,終點必須要猜出一開始的訊息是什麼。作為一個孩子或是學生這是一個非常好玩的遊戲,可以看到朋友彼此間出糗的畫面。

但假如今天是在實際的工作流程中呢?讓我們看看沒有良好跨團隊協作設計時會遇到的困難情境,導演請切畫面:

情境一:需求傳遞的失真效應

  • 產品經理:「我們需要一個用戶管理功能」
  • 前端工程師理解:簡單的 CRUD 操作界面
  • 後端工程師理解:完整的用戶權限管理系統
  • 結果:前端做了簡單表單,後端建了複雜的權限架構,完全對不上

情境二:UI/UX 設計的單打獨鬥

設計師畫出精美的單張線稿,但是:

  • 沒有考慮 API 資料結構限制
  • 缺乏不同狀態的設計(載入中、錯誤、空資料)
  • 忽略了行動裝置的技術限制
  • 結果:開發到一半發現設計無法實現,需要大幅修改

情境三:技術選型的各自為政

  • 前端團隊:選擇最新的 React 18
  • 後端團隊:堅持使用 PHP 5.6
  • DevOps 團隊:只熟悉 Docker 部署
  • 結果:技術棧不相容,整合時問題百出

情境四:API 開發的雞生蛋問題

前端:「後端 API 還沒好,我無法開發」
後端:「前端需求不明確,我不知道要提供什麼資料」
測試:「沒有 API 文件,我無法寫測試案例」
產品:「為什麼開發這麼慢?」

情境五:版本發布的協調噩夢

  • 前端完成了新功能
  • 後端還在修 bug
  • 資料庫 migration 需要停機
  • 結果:發布日延期,客戶不滿,團隊加班

情境六:知識孤島效應

情境:資深工程師 A 離職
問題:
- 核心系統沒有文件
- API 設計邏輯只有他知道
- 新人完全看不懂程式碼
結果:開發速度驟降,bug 頻出

這些場景是否似曾相識?假如引起了部分夥伴 PTSD 發作,我在這裡同樣抱持著 PTSD 發作時的悲傷心情向你致歉。這些各種靈異、驚悚乃至於黑色幽默的畫面鏡頭或多或少都出現在流傳的故事中。我也希望不會有人成為故事中的一員,這就是為什麼我們需要建立標準化的協作設計流程。

商業邏輯的素描

畫虎先畫骨 - 骨架的建立

在之前的文章中我們也提到一件事, 系統是商業抽象邏輯的實現 現在在經歷過一路從發想、情境確認、邊界與技術解決方案後,我們接下來可以試著將它具體下筆將其描繪出來。

在召開第一次正式的、包含開發團隊在內的啟動會議(Kick-off Meeting)之前,通常會有一段更早期的「產品發想與機會探索」階段。在這個階段,主要會啟動 4 個核心職務 : 業務發起人產品經理使用者體驗設計師技術主管,他們的工作是將模糊的想法塑造成一個可執行的專案雛形,先導目標主要是 對齊商業目標定義問題範疇驗證使用者需求並評估技術可行性 。當這些產出都具備雛形後,才能有效地召開第一次啟動會議,向更廣泛的開發團隊說明一個清晰、有共識、且可執行的專案方向。

在探索階段中,每個角色都有其被發起的原因, 業務發起人 作為擁有一項商業目標或待解決的痛點不說,產品經理 在這個過程中負責將模糊的商業目標轉化為具體的產品願景與策略。他們是商業需求和產品解決方案之間的橋樑,定義專案的 "Why" 與 "What"。接下來則是 設計師 確保團隊從一開始就以使用者為中心而不是在打造一個沒人會用的東西。最後,為了確保產品願景不會與技術現實脫節,技術主管負責從技術角度評估可行性,並識別潛在的技術風險與限制,從而避免設計稿很美好但現實中實現成本過大。

業務發起人

  • 身分意涵 : 需求的源頭,擁有一項商業目標或待解決的痛點,沒有他們,專案就不會存在。
  • 預期產出文件:
    • 商業目標 (Business Goal): 明確定義「我們想達成什麼」,例如:「提升客戶滿意度 10%」或「將訂單處理時間縮短 50%」。
    • 問題陳述 (Problem Statement): 清晰描述當前的痛點與挑戰。

產品經理

  • 身分意涵 : 負責將模糊的商業目標轉化為具體的產品願景與策略,建立商業需求和產品解決方案之間的橋樑,定義專案的 "Why" 與 "What"。
  • 預期產出:
    • 產品願景文件 (Product Vision Doc): 描述產品的目標使用者、要解決的問題以及它與眾不同的地方。
    • 初步使用者故事/史詩 (Initial User Stories/Epics): 高層次的功能描述,用來勾勒產品範圍。
    • 市場與競品分析 (Market/Competitor Analysis): (可選) 了解市場現況,為產品定位提供依據。

使用者體驗設計師

  • 身分意涵 : 負責確保團隊從一開始就以使用者為中心,探索使用者的真實需求與行為,確保團隊不是在打造一個沒人想用的東西;專注於 "Who are we building for?"
  • 預期產出:
    • 使用者旅程地圖 (User Journey Map): 視覺化呈現使用者為達成目標所經歷的流程、感受與痛點。
    • 低保真線框圖 (Low-fidelity Wireframes): 簡單的草圖或方塊圖,用來快速溝通佈局與流程概念,而非視覺細節。

系統分析師 a.k.a 技術主管

  • 身分意涵 : 負責從技術角度評估可行性,並識別潛在的技術風險與限制。在最早階段介入,是為了確保產品願景不會與技術現實脫節,回答 "Can we build it?" 的問題。
  • 預期產出:
    • 技術可行性評估報告 (Feasibility Study): 分析構想是否可行,可能需要哪些技術,以及潛在的整合挑戰。
    • 系統邊界圖 (System Context Diagram): 一張高階視角的圖,標示出我們的系統、使用者以及需要互動的外部系統。
    • 技術風險清單 (Technical Risk List): 列出可能影響專案的技術未知數或障礙。

在對於我們即將誕生的系統有了個初步的共同核心認知後,接下來不是要帶蜂蜜與乳香給他,而是開始進行 情境的發散

在核心商業邏輯被初步實現後,我們就可以根據現有資訊進行一場探索業務領域的協作,方式有很多種,像是會議或是工作坊,目標是建立團隊對於業務流程的共同語言與理解。這樣一來就比較能確保 「我們正在打造對的東西 (building the right thing)」,然後在進入 「把東西做對 (building the thing right)」 時才不會出現南轅北轍的窘境。

但在這個協作討論過程中,團隊成員對複雜的業務流程沒有共同的理解,導致溝通不暢、實作錯誤是常見的一個情境。或許先導部隊(Pioneer)已經有了初步的範型概念,但就像我們在之前舉的 「傳聲話筒」 遊戲例子,在這個討論的過程中初始的概念會逐漸模糊化與失焦到最後導致開發與商業目標脫鉤。團隊忙於開發功能,卻不確定這些功能是否真的能幫助公司達成商業目標而淪為「功能工廠」。這是因為當一個系統的業務邏輯非常複雜,牽涉到多個部門或角色時,每個人腦中的認知都可能是片面的 - 就算有了初步的文件做邊界限定。

所以接下來我將用我登山嚮導經驗中的一個登山目標策略制定方針來一同討論在制定一個目標規畫時,我們可以有什麼方法來進行討論並將成功登頂的路徑繪製下來。

接下來,我們將向著世界最高峰 - 聖母峰,吹響征服的號角。

向著眾神之巔前行 - 邁向目標的方法論

困難一. 知識孤島與流程模糊

在攻頂聖母峰前,最重要的就是讓所有嚮導、雪巴與登山隊員對路線有共同的認知。如果嚮導腦中的路線是從南坡走,但雪巴卻以為要從北坡運補給,那災難就不遠了,我們必須要清楚會經過那些途徑,我該怎麼開始?要抵達哪個國家?我的補給站有哪些?。團隊最怕的就是每個人對「路線」的理解都只是片面的,這時的核心問題是:「我們的攻頂路線到底發生了什麼事?」(我們的業務流程到底發生了什麼事?)Event Storming (事件風暴) 正是解決此問題的最佳方式。它就像把所有核心成員關在一個房間,攤開一張巨大的聖母峰地圖,要求大家用便利貼標示出從「抵達加德滿都」到「成功登頂並返回」之間所有關鍵的「事件」,每一個小型目標可能就包含了背後獨特的業務邏輯 - 而這其實就是 領域(Domain) 的實作! 例如:裝備已完成檢點已抵達基地營已通過昆布冰瀑第四營已建立。這個過程能快速建立一條共享的攻頂藍圖,並暴露所有人的知識缺口與錯誤假設。

困難二. 待辦清單失去脈絡

即使路線明確了,接下來的裝備清單也可能是一場混亂。如果我們只拿到一張寫著「冰爪、氧氣瓶、繩索、高山靴、能量棒」的扁平清單,我們很難知道哪些是為了基地營適應,哪些是為了最終攻頂衝刺。這時的核心問題是:「我們該先準備什麼?登山者如何從頭到尾完成這次遠征?」(使用者是如何使用我們的產品來完成他的目標的?)。若無法回答,團隊都將難以定義出第一階段「海拔適應」的 最小可行裝備(MVP) 。為此,User Story Mapping (使用者故事地圖) 提供了絕佳的視角。它將扁平的 裝備(功能) 清單,沿著 「使用者活動的先後順序」 (例如:抵達尼泊爾 -> 基地營健行 -> 海拔適應 -> 攻頂與下撤)展開,變成一張有脈絡的地圖。這讓團隊能鳥瞰整個遠征計畫,並能輕易地從中水平切分出「第一階段:基地營適應」所需的核心裝備與任務,以確保每個 裝備(功能) 都能提供連貫且有價值的作功。。

困難三. 開發與商業目標脫鉤

但在進行規畫的時候,有時團隊會陷入一個陷阱:我們很擅長採購裝備、訓練體能,於是就不斷地買裝備、做訓練,變成高效的「遠征準備工廠」。變成技術精湛的登山家,僅忙著鍛鍊最強的體魄,卻沒有人去確認這次攀登的最終目標是為了 「商業贊助曝光」 還是 「科學研究」 。當團隊的成功只用「採購了多少頂級裝備」來衡量,而不是「是否達成了遠征的商業價值」時,就產生了一個致命問題:「我們做的這些準備,真的能幫助贊助商達成目標嗎?」(我們為什麼要做這個?)Impact Mapping (影響力地圖) 正是為了解決這個問題而生,它強迫團隊從終點(Why - 商業目標,如:提升品牌曝光率30%)開始思考,反向推導為了達成目標需要影響誰(Who - 媒體記者)、我們希望他們的行為如何改變(How - 發布攻頂成功的新聞稿),最後才決定我們該做什麼(What - 在頂峰拍攝品牌旗幟)。這確保了每一次的準備,都與最終的商業價值緊密相連。

困難四. 未挖掘出真實動機

在進行路徑規劃時,為了有一個粗略且被涵化的共同認知,我們常會定義參與團員的 角色側寫,例如「Mike,30 歲的企業家,喜歡極限運動」。但這就像嚮導只根據客戶的職業和年齡就規劃路線,卻沒問他為什麼想登山。我們可能規劃出一條 Mike「應該」會喜歡的挑戰路線,卻沒解決他真正的渴望(在社群網路中大紅大紫、自我實現又或是單純想吸引某個人的注意力?)。問題的核心在於:「客戶為什麼要『雇用』我們帶他去登山?他想完成的內心任務是什麼?」(使用者想『雇用』我們的產品來完成什麼『任務』?)。傳統方法讓我們專注於「登山者是誰」,卻忽略了他們想「完成什麼任務」。Jobs to be Done (JTBD) 理論提供了一個新視角,它讓我們去探究客戶在「人生遇到瓶頸」的「情境」下,想要「雇用」一次聖母峰攀登來「完成」「證明自我、尋找突破」的「任務」。理解這點,我們提供的可能就不只是一條路線,而是一整套能幫助他反思與成長的體驗。這幫助我們挖掘客戶最深層的動機,從而設計出真正能觸動人心的遠征方案。

現在,我們知道了如何與團隊一同成就,在泰拉最高處的的地方觸碰宇宙的顏色。

經由這些方法論與套論後的情境邊界設定,我們對於整個 登山路徑(系統脈絡) 就會變得清楚,知之為知之大家都知道是重要的,但要達成是知也的前提是也要知道 不知為不知

  1. Event Storming (事件風暴)
  • 切入點: 「我們的業務流程到底發生了什麼事?」
  • 驅動原因: 當一個系統的業務邏輯非常複雜,牽涉到多個部門或角色時,每個人腦中的認知都可能是片面的。開發者不理解業務,業務人員不理解系統限制。
  • 解決方案: 它透過一個協作工作坊,讓所有利害關係人(業務、PM、開發、測試)一起,用便利貼將業務流程中所有已發生的「領域事件 (Domain Events)」(例如:訂單已成立、款項已支付) 按時間序排列出來。這強迫大家建立一個對整個流程的共享藍圖,從而發現知識缺口和誤解。
  1. User Story Mapping (使用者故事地圖)
  • 切入點: 「使用者是如何使用我們的產品來完成他的目標的?」
  • 驅動原因: 傳統的產品待辦清單 (Product Backlog) 就像一張長長的購物清單,缺乏上下文。團隊很容易迷失在單一功能中,忘記了這些功能如何串連成一個完整的使用者體驗。
  • 解決方案: 它將使用者故事按照「使用者活動的先後順序」進行二維排列,形成一張地圖。這張地圖的「骨幹」就是使用者的旅程,幫助團隊從頭到尾鳥瞰產品,並能輕易地在上面劃分出哪個版本該包含哪些功能,以確保每個版本都能提供連貫且有價值的體驗。
  1. Impact Mapping (影響力地圖)
  • 切入點: 「我們為什麼要做這個?它能帶來什麼改變?」
  • 驅動原因: 很多專案在開始時只定義了要「做什麼 (What)」,卻沒有清晰地連結到「為什麼 (Why)」。導致開發團隊交付了功能,但商業指標(如營收、留存率)卻沒有提升。
  • 解決方案: 它是一個策略規劃工具,強迫團隊從最終的「商業目標 (Goal)」出發,反向推導:為了達成這個目標,需要影響哪些「角色 (Actors)」?我們希望他們的「行為產生什麼改變 (Impact)」?最後才思考「我們該做什麼功能 (Deliverable)」來促成這個改變。它確保了每一份開發努力都與商業價值直接掛鉤。
  1. Jobs to be Done (JTBD)
  • 切入點: 「使用者想『雇用』我們的產品來完成什麼『任務』?」
  • 驅動原因: 傳統的使用者畫像 (Persona) 描述了「使用者是誰」(例如:35 歲,住在大城市,喜歡科技),但沒有解釋他「為什麼」會在此時此刻需要一個解決方案。這可能導致團隊打造出一個符合使用者輪廓,卻無法解決其根本問題的產品。
  • 解決方案: JTBD 框架將焦點從使用者本身轉移到他們所處的「情境」和想要達成的「進展」。它認為使用者是為了完成某項「任務」才「雇用」產品。透過理解這個任務背後的掙扎與動機,團隊可以設計出更能切中要害、甚至更具創新性的解決方案。

經過前面的初期探索,以及方法論洗禮,我們的核心團隊終於對這趟遠征有了清晰且深刻的共識。我們不僅繪製了攻頂的 路線圖 (業務流程),規劃了每個階段的 行程 (使用者故事地圖),確立了此次攀登的 商業目的 (影響力地圖),更洞悉了登山者內心深處的 渴望 (Jobs to be Done)

至此,我們成功地回答了「我們為什麼要去?」和「我們大致要去哪裡?」這兩個戰略層面的問題。因此,在進入大規模開發、也就是「把東西做對 (building the thing right)」的階段前,我們必須將這份高層次的共識,轉化為一份所有技術團隊都能理解並遵守的、具體的、可執行的技術文件。這份藍圖,就是我們接下來要談的「共同契約」。


上一篇
Day 12 | 版本控制策略(PRReview strategy) × Git Flow × Lint 導入思維 :管理學方法論、代碼品質管控與開發流程規範
下一篇
Day 13-1 | 跨團隊協作設計:技術文件、OpenAPI、共用契約 : API 文檔化與團隊協作標準建立 - 可文檔版控的視覺化商業邏輯具象(1):共用契約 (Shared Contract)
系列文
AWS架構師的自我修養:30天雲端系統思維實戰指南26
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言