[13]_數位產品PM的開發小抄本_SEPC撰寫要點

規格文檔,會需包含未來、現在、過去的內容,因此也需要做好版本控制,避免現在執行項目的人員,誤判仍在設計中的未來項目

SPEC就是泛指產品要被開發時的依據規範及條件,讓是全體開發人員有一個依據文件可以參照。

用一個文件管理系統做到規格敘述說明(SPEC)、編年史完整(Chronicle)和迭代(Iteration)的內容

你的產品有多好並不重要,因為如果它的文件不夠好,人們就不會使用它。即使他們因為別無選擇而必須使用它,如果沒有良好的文檔,他們也不會有效地使用它或按照您希望的方式使用它。

規格文檔,會需包含未來、現在、過去的內容,因此也需要做好版本控制,避免現在執行項目的人員,誤判仍在設計中的未來項目,有需要一並開發;也避免SQA在Q時,看到未來內容,以爲是RD未開發。

盡可能每一個規則都會有替代規則,例如讀不到資料或無資料時,要採用什麼替代圖片與提示文字。

文件框架

目前看過彈性較高的文件架構就是「The Documentation System」這一個由divio提出的模式,這文件架構,對於每一個關係人都會有想相對應的內容可以取得,也對於執行者可以有前後脈絡依據的內容的參考,而運用這個架構撰寫產品SPEC,比較有效率的將同一份內容應用不同情境

框架特色

  • 每個象限與其兩個相鄰象限相似,讓每一個人從那一個象限角度開始閱讀,都可以獲得必要資訊。
  • 教學說明和操作指南將會描述描述實際步驟,以利於閱讀者理解。
  • 操作指南和技術參考主要都描述在執行任務、Coding人員時所需要的資訊內容。
  • 參考指南和解釋都會包含理論知識內容。
  • 教程和解釋在我們瞭解學習這文件內容時使用。

象限列表說明

Tutorials 教學How-to guides 操作指南Reference 參考Explanation 解釋
oriented to 面向learning 學習a goal 一個目標information 資訊understanding 理解
must 必須allow the newcomer to get started
讓新人能上手
show how to solve a specific problem
展示如何解決特定問題
describe the machinery 描述機器explain 解釋
its form 它的形式a lesson 一堂課a series of steps 一系列步驟dry description 幹描述discursive explanation 話語解釋
analogy 比喻teaching a small child how to cook
教小孩如何做菜
a recipe in a cookery book
烹飪書中的食譜
a reference encyclopaedia article
參考百科全書文章
an article on culinary social history
一篇關於烹飪社會史的文章

Take away

真正的困能的是要即時更新和維護文件,必免資訊斷層,但這就是難的地方,如果體制小組織還容易同步,但如果體制大時,同步就會變得很緩慢困難。

撰寫SPEC的原則,應該保持的讓每一個都方便可以取得,並且可以易於理解內容後,執行相對應的專案的內容,因此不要把SPEC文件,當作神書在撰寫,會造成很多不必得要的紛爭。


內容同步刊載於2024IT鐵人賽