哈囉，朋友

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

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

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

如果我們要進行一場猜拳，規則如下：

1. 猜拳機制中，每次進行單一回合行動，由兩方參與者進行對抗
2. 單一回合中，兩方需同時出拳，展示所選的拳形用以產生判定結果
   1. 判定結果有兩種：一贏一輸、平手
   2. 雙方拳形不同則一贏一輸，回合結束
   3. 雙方拳形相同則平手，重新出拳
3. 兩方參與者只能從以下三種拳形做出選擇
   1. 剪刀
   2. 石頭
   3. 布
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