Soking 來信:8個產品設計文件 PRD 的 SPEC 書寫原則小技巧


哈囉,朋友

你曾經寫過所謂的「規格文件」要提供給開發人員實作嗎?

我最常被詢問的議題通常包括「到底要寫到多細?」、「有沒有 PRD 模版可以照填就好?」、「我又不會寫程式,要怎麼樣才能讓工程師看懂?」等等。

其實寫規格文件的時候,重點在於把「如何使用資訊物件的規則」想清楚,讓我用猜拳遊戲來舉例。

如果我們要進行一場猜拳,規則如下:

  1. 猜拳機制中,每次進行單一回合行動,由兩方參與者進行對抗
  2. 單一回合中,兩方需同時出拳,展示所選的拳形用以產生判定結果
    1. 判定結果有兩種:一贏一輸、平手
    2. 雙方拳形不同則一贏一輸,回合結束
    3. 雙方拳形相同則平手,重新出拳
  3. 兩方參與者只能從以下三種拳形做出選擇
    1. 剪刀
    2. 石頭
  4. 展示拳形之後,判定結果的規則如下:
    1. 出剪刀,贏布
    2. 出石頭,贏剪刀
    3. 出布,贏石頭
    4. 兩方拳形相同,平手重來
  5. 若有一方延遲出拳,該次判定結果無效,重新出拳。

在這個案例當中,我使用的元素包括

  • 猜拳(機制名稱)
  • 兩方(參與者角色)
  • 回合(整體流程的抽象單位)
  • 出拳(特定行為)
  • 拳形(資訊物件)
  • 判定結果(資訊物件)

其實整個猜拳機制簡化來看,就是輸入任意兩個隨機的「拳形」,用來獲得「判定結果」。

一樣的概念可以套用到許多軟體功能需求上,例如購物車流程本質上也是「輸入會員、商品、金物流等資訊,用來新增一筆訂單。」、而請假人事系統本質上也是「輸入職員、請假事由等資料,經過管理者審核,留下請假記錄。」

在猜拳裡面的「回合」(整體流程的抽象單位),到了購物車的時候就是「結帳」。

在猜拳裡面輸入的「拳形」(資訊物件),到了購物車的時候就是「會員、商品、金物流等資訊」。

在猜拳裡面的「判定結果」(資訊物件),到了購物車的時候就是「訂單」。

所以我們可以這樣理解,寫 SPEC 規格文件,就像是在寫一道菜的食譜,你要描述輸入哪些原料、使用什麼工具、按照什麼順序、注意哪些狀況,最後輸出什麼結果。

理解了這個基本概念之外,我也整理了幾個實用的書寫原則小技巧分享給你:

  • 資訊物件的命名技巧:抽象但指意明確
  • 描述行為的動詞:維持一致且獨特
  • 常見通用詞:特徵具體且唯一
  • 使用直述句
  • 順著脈絡書寫
  • 先談理想再補漏洞
  • 區別業務邏輯與機制規則
  • 善用舉例

▋資訊物件的命名技巧:抽象但指意明確 ▋

在猜拳機制的案例中,我命名了一個概念叫做「拳形」,用這個概念來包含剪刀、石頭、布這三種選項。

拳形是剪刀、石頭、布這三種選項背後共通的抽象概念,使用「拳形」這兩個字,也容易令人聯想到拳頭的形狀,這便是資訊物件命名時的一個技巧,維持抽象,但指向性意圖明確。

資訊物件是我們在書寫規格時很重要且常用的「概念主體」,用於聚合同質性的內容。

就像水本來沒有形狀難以測量,但一杯水就成為了可以測量以及運算的單位。 資訊物件的命名,就是將本來無形的資訊,給予一個框架,便於理解與運算。

當杯子裡面的液體可能會裝氣泡水、果汁還是酒的時候,其共通特性是可以直接飲用。 所以我們可以將其命名為「飲料」,此時也排除了橄欖油、醋等液體。

這就是根據資訊的內容物「氣泡水、果汁、酒」,取其相同的抽象概念命名為「飲料」,並且不會跟「橄欖油、醋等液體」搞混,同時符合指意明確的原則。

▋描述行為的動詞:維持一致且獨特 ▋

在運用資訊物件的時候,應該根據其內涵來決定相關操作行為的動詞。

例如在猜拳機制當中,運用「拳形」這個資訊物件時的行為,叫做「出拳」。

當然你也可以叫它「行動」或「輸入選項」,但這麼一來你就很難分辨這個行為與系統當中的其他行為有何不同了。

描述針對特定資訊物件的行為時,所挑選的動詞,最好要獨特有辨識性,這能幫助開發者理解意圖的不同,也能在日後互動介面設計時,作為 UX writing 撰寫 CTA 時的參考。

描述行為的動詞也應該保持一致性,如果你一下稱呼出拳、一下稱呼行動,會增加別人的認知負擔,要想一下才能辨認出這是在指相同的行為。

▋常見通用詞:特徵具體且唯一 ▋

在一個系統中最常的通用詞就是時間、日期等單位。

如果我們在寫規格文件或是命名欄位時,也都只順手寫成「日期:2024/2/12」,最大的問題在於別人可能猜測不出來你指的是什麼日期?

比起「日期:2024/2/12」 更好的寫法是「發佈日期:2024/2/12」

比起「名稱:王大」 更好的寫法是「會員名稱:王大」

▋使用直述句 ▋

人的腦袋最適合直述句的語意。

不適合的寫法,就是以倒裝句或副詞子句來書寫,因為會增加認知負擔。

上面兩行字分別使用了直述句以及倒裝句,你可以比較一下閱讀感受。

倒裝句或副詞子句都是需要閱讀者記住前後脈絡的書寫方式,不容易一目了然。

以猜拳機制為例

  • 好的寫法:兩方參與者只能從以下三種拳形做出選擇
  • 不好的寫法:以下三種拳形是兩方參與者的可選擇項目

先宣告主詞,再描述後續的行為動作。

這是比較無聊的寫法,但規格文件不是文學作品,重點在於一目了然。

▋順著脈絡書寫 ▋

前面提到,寫規格文件的 spec 就像在寫食譜,因此順序很重要。

例如現在要寫猜拳的機制,很容易腦袋裡面想的都是剪刀贏布之類的判斷規則。

但其實更重要的是這個機制如何運作的流程。

因此最好的寫法是想像一個毫無概念的人在你眼前,你要從頭開始給他訊息,按照順序建立概念之後才能解說細節的行為規則。

▋先談理想再補漏洞 ▋

有書寫規格文件經驗的人,往往很害怕漏寫邊緣案例(Edge case),就是那些發生概率低,但可能造成機制出問題的事情。

邊緣案例當然是工程師閱讀規格文件時的檢查重點。

但前提是你的主要理想路徑先讓人看懂,才會輪到邊緣案例。

先寫主要理想路徑,然後再根據可能出問題的步驟流程,針對性的補充邊緣案例敘述。

▋區別業務邏輯與機制規則 ▋

有許多需求方在閱讀你寫的規格文件時,會把他想怎麼操作的業務邏輯告訴你,因為他擔心這些事情不知道能不能在未來開發的程式功能上面看到。

例如「早上9點之前不能預約」

而你真的按照字面上的業務邏輯說法,去要求工程師這麼做,讓工程師寫成機制的判斷規則。

結果過一兩個月,需求方跑來跟你說「欸,我們想弄個早起鳥兒活動,為什麼不能開放上午六點呢?」

你才恍然大悟,原來預約這件事情「早上9點」並不是鐵律。

因此另外一個作法是,你提供一個機制規則,幫助需求方實現業務邏輯。

比起程式裡面判斷「早上9點之前不能預約」(快速實現,但不容易改動)

你還可以寫成「營運人員可設定開放預約時間」(規劃較慢,但擴充性高)

▋善用舉例 ▋

通篇規格文件寫下來,充滿各種抽象的詞彙,看久了也會迷失在抽象的世界中。

因此雖然命名要抽象,但書寫過程還要適度的具體舉例。

例如,猜拳的時候有「拳形」,那我們就要舉例「剪刀、石頭、布」。

例如預約英語老師線上教學的時候有「課程類型」,那就要舉例「多益英文、旅遊英文、職場商務對話」。

適當的舉例,讓閱讀文件的開發者可以更具體的理解情境,也讓需求方想像未來會如何運用此功能機制。

以上 8 個 SPEC 書寫原則分享給你,也歡迎你轉寄分享給其他你覺得需要的朋友。

希望能對你的工作有所幫助。

by Soking

Soking

千綺創意設計 Co-Founder / 產品設計總監,目前經營軟體領域的體驗設計顧問公司,也從事 UX 教學,喜歡以工作坊形式,引導你體驗 UX 領域的專業知識。 工作聯絡:service@soking.cc

Read more from Soking

哈囉,朋友 如果你在工作上要去執行需求訪談,相信也曾遇過不耐煩的受訪者。 尤其是主管位階的大忙人,特別沒耐心受訪。 或許你會想,可能是自己的職稱不夠高,所以對方才不耐煩。 但換個情況,如果我們是主管,然後總是對於跟位階低的人講話不耐煩。 那這樣要如何領導其他人呢? 所以有沒有一種可能,不是我們位階低,而是對方感覺這次的談話是沒有用的。 就我自己的親身經歷,最常見以下幾種狀況: 同樣事情他已經講了一百遍 沒有人可以了解他在幹嘛,忙得喘不過氣 你想訪談的東西他覺得跟他無關 因此我想與你分享一下,這幾類狀況的訪談應對策略。 ▋狀況一:同樣事情他已經講了一百遍 除非對於一件事情有使命狂熱,講個千遍也不厭倦。 不然任誰同一件事情講十次以上應該都會超級不耐煩吧? 講了十幾遍之後,他覺得自己已經付出了沈重的代價。 然後此時再來一個什麼都不懂的人,這情況簡直糟得不能再糟糕了。 因為有更多的事情得從頭講起。 那該怎麼辦呢? 讓對方意識到你也付出了一些沈重的代價,但沒有找到答案,所以來到了他的面前。 例如對方跟組織內的同事講過許多次了。...

哈囉,朋友 原本預計今天寫給你們的一封信,被我收進了草稿匣,因為變成了奇幻小說,而我不知道該怎麼向你們介紹而不顯得突兀。 如果你有追蹤我的臉書,最近的我,正處於內在衝突的自我整合歷程,因此不斷萌發各種念頭,看起來不太像在說人話,先跟你們抱歉。 我想改成與你分享,最近我們團隊正在籌備的一場直播講座的調查狀況。 這個調查主題是關於「side project」,當你接觸網路軟體產業之後,或多或少應該聽過這件事情。 有些人想透過 side project 來提升自己的能力,有些人想透過 side project 打造屬於自己的解決方案或工具,有些人渴望透過 side project 讓自己更快樂、有成就感。 我自己常常發起屬於自己的 side project,大多數在當下都沒什麼用,但可能在日後突然串了起來,在某個專案中起了絕妙的用途。 因為這樣,我常常被誤認為是有創意的人。 但我其實不是有創意的人,而是嘗試過一百種當時不可行的辦法,並且記錄、分類、保存下來。 因此 side project 對我來說,就是用來失敗的。 那我是怎麼遇見想要的 side project 呢?...

哈囉,朋友 或許你也曾聽別人說:「我對於人很感興趣,所以想從事 UX 相關的工作。」 至少我跟上百位學 UX 的朋友聊天時,這是最常被提到的理由。 對於從事 UX 相關職業的想像通常包含:可以數位遊牧遠端工作、可以研究人們的行為、薪水落在還不錯的區間等等。 不知道你有沒有聽過最近流行的潮名詞:多巴胺職業。 我認識的一位 SEO 專家邱韜誠 Frank,提出了這個有趣的概念。 多巴胺職業相對於傳統職業,更能帶給人們成就感、意義感以及創造性。 因此人們很容易受到多巴胺職業吸引,渴望從中獲得熱情與成就的自我實現。 ▋UX 相關的工作是什麼? 與 UX 相關的職業,目前主要集中於資訊軟體產業裡面的產品經理、UIUX 設計師、UX 研究員等職位。 因為 UX 這個趨勢崛起,來自蘋果電腦。 以用戶體驗為中心,打造符合人性的產品,獲得商業上的巨大成功。 蘋果電腦在賈柏斯的領導之下,重新定義了「產品設計」,成為地球上第一家市值超過一兆美元的科技公司。 用戶體驗設計,就是蘋果電腦的祖傳靈魂配方。 ▋UX 在業界的現實 蘋果電腦帶著 iPhone 征服許多人,Mac...