軟體開發文件SOP及範本
tags: 軟體開發 開發 軟體 文件 SOP
- 時間：2017-09-10
- 作者：洪育昇(Mars.Hung)
- 主題：軟體開發文件SOP及範本
○、說明
- 為了幫助開發過程中的需求理解及伙伴間討論，並提高效率、可靠性，在此定義開發文件書寫原則，並提供範本。
- 開發文件如同建築藍圖，是在建構實體物件之前的規劃、設計，用書面方式推演執行細節及相關外部因素，最後得到符合SMART原則的工作項目、驗收項目。
SMART原則：Specific（明確）、Measurable（可衡量）、Achievable（可達成）、Relevant（相關）和Time-bound（有時限）。
程式開發有三個關鍵：整體性、關聯性、循環性。
整體性就是最終成品的樣子，有整體概念才能掌握各功能間的關聯
關聯性就是所有環節是一環扣一環，不會出現失落環節狀況
循環性就是傳出的資料接得回來，進資料庫的資料拿得出來，即CRUD
畫Mind Map, Flowchart, ER Model是學習以上二點的最好方法
一、書寫原則
- 文件先行：文件書寫快，程式實作慢，文件重寫成本低，程式重寫成本高。利用寫文件推演出如何有效實作程式是很重要的技巧。
- 同步更新：文件、程式內容不符是很糟糕的事。
- 思維整理
- 條理化、具體化、流程化
- 交流標的
1.1 Why: 理解要做的事 - 記錄思考過程
程式開發起始於客戶訪談，從訪談中得知為什麼要做，要得到什麼結果，訪談如同故事，敘述著前因後果，因此理解要做的事是首要的。
- 需求閱讀：對PM規畫文件/使用者需求的理解，並拆解出條列化的需求清單及使用案例。
- 需求分析：對需求如何轉化成具體實作的思考過程。
- 討論依據：文件是記錄理解的過程、思考的過程，是反思、討論、交流的依據。
- 別期待工程師有一張業務般靈巧的嘴。
- 片面的交流有可能是雞同鴨講，但文件化的規則整理和思路過程讓大部份問題明白程現。
- 在記憶力上金頭腦比不上爛筆頭。
- 期待聰明的頭腦不如培養個有智慧的習慣。
- 一步一腳印，記錄下思路過程，可見証自我的成長。
1.2 How: 要怎麼做 - 記錄實現流程
- 層次：程式設計是 人性面的需求 跟 機械面邏輯 的轉化過程。
- 從結構：前端使用者介面 <=> 後端資料處理 <=> 資料庫儲存
- 從開發：故事 <=> 需求 <=> 案例 <=> 功能/流程 <=> 頁面(UI) <=> 資料欄位 <=> 前後端資料交換 <=> 處理函式 <=> 工作項目 <=> 測試項目
- 變動：程式設計的過程中可能要Debug、需求變更、重構、優化，是需要反復作業，甚至修改的。
- 記錄：文件是開發過程中輔助思考及N年後優化時輔助記憶的好幫手。
- UI: User Interface 使用者介面
- 交流討論必需有依據才有焦點、才有效率。
- 對開發瑣事與期頻繁的集合開會，不如隨筆記錄文件的交流，起碼可以多人隨時隨地的查閱。
- 使用推衍流程具體化，不但攤開大部份問題，而且產品經理、程序員、業務都看得懂，可參與檢視。
1.3 What: 記錄人看得懂的資料 - 交流討論的依據
- 說明: 本次專案執原因/目標/發展性
- 需求: 需求條列/來源/分析
- 案例: 假設情境，並推衍使用過程
- 功能: 實現步驟/流程
- 畫面: 功能畫面
- 資料: 資料欄位、資料格式、交換格式、抽像類別、介面類別
- 邏輯: 實現過程的業務邏輯
- 定義: 各種規則
- 圖表: 各式建構圖表、物件關系圖
- 工項: 條列化工作項目，以明確工作目標及估時
- 測試: 條列化測試內容，以確保產品品質
- 問題: 記錄開發過程中的問題以便討論時解決
1.4 每次思考請限時
- 思路卡住就去做別的事，換個想法，別浪費時間。
- 大案文件大，小案文件小，沒東西寫就別硬擠了。
重點 : 每次思考請限時…… 每次思考請限時…… 每次思考請限時……
二、思考技巧：
2.1 思考方向
- 從 人性化需求面 出發，向 機械化邏輯面 使用不同角度、不同深度分析
2.2 深入思考方式
- 漸進式：從 明顯、抽像化概念 一層一層向 底層、具體化實作 前進
- Level-1 : [使用者介面] 使用者 操作頁面,動作流程,I/O(輸入,上傳,下載…)
- Level-2 : [程式面] Level-1 過程細化動作 - 資源、產出物、節點/轉折點、流程、資料交換、狀態變化
- Level-3 : [資料面] 各 變數/資源/資料庫/檔案 的 I/O、資料轉換、資料對應
- 從結構：前端使用者介面 <=> 後端資料處理 <=> 資料庫儲存
- 程式的使用，是由使用者(前端)點選功能，(跟後端)讀取資料後反應給使用者(前端)
- 從開發：故事 <=> 需求 <=> 案例 <=> 功能/流程 <=> 頁面(UI) <=> 資料欄位 <=> 前後端資料交換 <=> 處理函式 <=> 工作項目 <=> 測試項目
- 程式的開發，必定是環環相扣，一層一層的推演下去，推演不下去，可回去檢視上層是不是有缺漏
- 層次間的關系：上層如同問題，下層如同解答/闡敘，每一個問題都要的對應的解答。
- 如果專案較小，可以省掉部份項目，改用文字敘述方式解答。
2.3 思考焦點：
- Level-1 : 資源(Resource)、產出物(Product)。 (二個推衍方向)
- Level-2 : 節點/轉折點(node)、流程(Flow)。
- Level-3 : 資料交換、資料結構、狀態變化(state)。
- 功能動作是推衍的最小單位；物件是實作的最小單位。
- 文件中的推論都是承上啟下的。
- 無法推衍下去的通常是問題點。
2.4 思考角度
- 角度可能有：資料收集 (擇要取用)
- 目標說明 : 說明為什麼要這麼做
- 需求收集 : 需要做些什麼
- 案例收集 : 哪些狀況下要這些需求。 [UML使用個案圖]
- 功能產出(I/O)列表 : 需求的具體化，依照哪些資訊，產出哪些東西
- 使用頁面 : 可能要用哪些頁面達成
- 欄位收集 : 可能用到的表單欄位、流程控制參數、資料庫狀態欄位
- 可能函式 : 可能可以動作化、步驟化、方法化的工作，並命名
- 職責(目的)相似的函式，可以集合成類別(物件)
- 不同物件間相似的函式，可以設計成界面
- 有衍生關係的類別(物件)，可以設計成抽像類別(物件)
- 工作項目 : 開發的具體工作項目、時間
- 測試標的 : 需要測試的項目及如何測試
- 思考角度與思考深度的關系：思考角度如同問題，思考深度如同解答/闡敘，每一個問題都要的對應的解答。
- 思考角度前後項間的關系：前項如同問題，後項如同解答/闡敘，每一個問題都要的對應的解答。
- 如果專案較小，可以省掉部份項目，改用文字敘述方式解答。
2.5 思考深度
- 深度可能有：資料分析 (擇要取用)
- 需求分析 : 哪些需求可以結合；哪些可以細化；哪些要捨去
- 案例分析 : (人事時地物) 狀況 => 需求 => 產生 => 狀況 => 需求 => ….. => 結束
- 流程分析 : 功能處理資訊流程、狀態變更、資料產出。 [流程圖] [UML活動圖] [UML狀態圖] [UML時序圖]
- 頁面分析 : 依照案例分析、流程分析，哪些東西可以結合成一個頁面
- 資料庫設計 : 依收集的欄位試建資料庫。 [Database Schema] [E-R圖]
- 資料格式分析 :
- 流程確定，可定義 流程控制參數、資料交換格式。
- 資料欄位確定，可定義 物件資料格式。
- 函式設計 : 依收集的函式試建 物件、介面、類別。 [UML類別圖] [UML物件圖] [UML組件圖]
- 安排工作項目 : 工作項目有相關性，也有順序
- 細化測試項目 : 條列化、表格化，需確定 需求、案例、動態頁面 都有被測到。
- 思考角度與思考深度的關系：思考角度如同問題，思考深度如同解答/闡敘，每一個問題都要的對應的解答。
- 思考深度前後項間的關系：前項如同問題，後項如同解答/闡敘，每一個問題都要的對應的解答。
- 如果專案較小，可以省掉部份項目，改用文字敘述方式解答。
三、設計圖、範例圖、參考圖
3.1 設計圖種類 (擇用)
- 流程圖
- E-R圖
- 甘特圖
- Database Schema
- UML使用個案圖
- UML活動圖
- UML狀態圖
- UML時序圖
- UML類別圖
- UML物件圖
- UML組件圖
- 泳道流程圖
3.2 設計圖作法
- Wireframe: 靜態的「線框稿」
- Mockup: 靜態的「視覺稿」
- Prototype: 可操作的「原型」
軟體繪圖
- 使用繪圖軟體畫完圖後貼到文件中輔助說明
螢幕截圖
- 可直接從螢幕截取圖片貼到文件中輔助說明
手繪圖+拍照上傳
- 可將紙上繪圖、開會的白板中的文字，圖表拍照後貼到文件中輔助說明
文字敘述
- 部份圖表(如 流程圖)也可以使用文字敘述表示，如：
點選編輯 => [View]顯示編輯彈窗 => [View-Ajax+Ctrller]載入預設資料Request+Response => [View]前端資料驗證 => [View-Ajax]送出資料Request => [Ctrller]處理&回傳結果 => [View-AjaxResp]更新訊息 => 完成編輯
- 我們需要文件來當 反思、交接、討論、重構 的依據，只需 快速、示意 即可，不需正式、嚴僅、精美。
- SDD文件是程式設計過程的具體化，不應憑空想像。
- 不要貼一堆Detail的程式碼上來。
- 每次思考請限時
四、範本
五、參考
六、Log
- 2017-09: Mars Hung編寫於HackMD
- 2017-10: Mars Hung初版
- 2018-05: Mars Hung修訂
- 2019-07-30: Mars Hung重製成md檔
- 2019-11-29: Mars Hung 改版