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文件,當作神書在撰寫,會造成很多不必得要的紛爭。