軟體開發文件SOP範本

2017-09-11

Mars Hung

doc

文章閱讀量次

一、範本內容

一、範本內容

軟體開發文件(SRS,SDD,STP)範本
===

> 範例使用原則：
> - 請複制一份到自己新增的頁面再行修改
> - 不需要的項目請自行刪除
> - 如有沒有寫到的部份請自行增加
> - 如有需要，排版方式可自行變動

###### tags: `文件` `範本` `開發`

> - 開發日期: 2017-07-28  
> - 規劃者 : 名子 (如果有)  
> - 規劃文件 : 規劃文件路徑、網址 (如果有)  
> - 初步設計 : 名子 (如果有)  
> - 細部設計 : 名子 (如果有)  
> - 指導者 : 名子 (如果有)  
> - 參與名單 : 
>   - 名子 (如果有)

# 一、說明
> 簡述開發原因、目標、期許

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄

---

# 二、需求
## 2.1 需求收集
> SA : SRS文件  
> PM規劃、需求訪談、使用者反應  

## 2.2 需求分析
> SA : SRS文件  
> 需求收集的解答：需求結合、細化、捨去  

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄
>
> 需求收集、需求分析 可視狀況合併

---

# 三、案例
## 3.1 案例收集
> SA : SRS文件  
> 需求的解答/示範：可能案例描述  

## 3.2 案例分析
> SA : SRS文件  
> Who, What, When, Where, Why, How  
> 狀況 => 需求 => 產生 => 狀況 => 需求 => … => 結束  
> 案例收集的解答：分析過程可能會出現副產品 功能雛形/流程雛形  
> 副產品為此項目的解答方向  

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄
>
> 案例收集、案例分析 可視狀況合併

### 功能收集
### 流程收集

---

# 四、功能
## 4.1 功能劃分
> SA : SRS文件  
> 案例/需求的解答：將需求劃分成具體功能  

## 4.2 功能流程分析
> SA : SRS文件  
> SD : SDD文件  
> 功能劃分的解答/推衍：功能實現流程的具體推衍，注意收集副產品  
> 副產品為此項目的解答方向  

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄
>
> 功能劃分、功能流程分析 可視狀況合併

### 頁面 收集
### 狀態/控制參數 收集
### 欄位/資料內容 收集
### 細部動作/函式 收集

---

# 五、頁面
## 5.1 頁面統整
> SA : SRS文件  
> SD : SDD文件  
> 功能/流程的解答：會用到的頁面清單  

## 5.2 頁面分析
> SA : SRS文件  
> SD : SDD文件  
> 頁面統整的解答：頁面具體排版、欄位、及動態畫面規則，注意收集副產品  
> 副產品為此項目的解答方向  

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄
>
> 頁面統整、頁面分析 可視狀況合併

### 狀態/控制參數 收集
### 欄位/資料內容 收集
### 細部動作/函式 收集

---

# 六、欄位
## 6.1 欄位統整
> SD : SDD文件  
> 收集會用到的資料欄位，並分類  

## 6.2 資料庫設計
> SD : SDD文件  
> 欄位統整的解答：依照分類好的資料設計Database Schema，並注意和其他資料庫關系  

---

# 七、資料格式分析/定義
## 7.1 流程控制參數、資料交換格式
> SD : SDD文件  
> 案例分析/流程分析/頁面分析的解答  
> 
> - Request:
>   POST/GIT/PUT/DELETE URL
>
> - Request Body:
>   {
>     'dataKey1': $dataValue1,
>     'dataKey2': $dataValue2,
>         :
>         :
>   }
>
> - Response:
>   {
>     'code': 200,  // HTTP狀態碼 200,400
>     'data': [$data],   // 回傳資料
>     'message': '',// 回傳訊息
>   }
>   
>   $data = {
>     'dataKey1': $dataValue1,
>     'dataKey2': $dataValue2,
>         :
>         :
>   }

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄

## 7.2 資料格式、物件格式
> SD : SDD文件  
> 案例分析/流程分析/頁面分析的解答  

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄

---

# 八、函式庫設計
### 8.1 影響 - 檔案結構
- 資料夾1
  - 資料夾2
    - 檔案1
    - 檔案2
  - 資料夾3
    - 檔案3
  - 檔案4

> 列出相關檔案結構有助於整體性的了解相關檔案

## 8.2 函式統整
### 8.2.1 前端函式
> SD : SDD文件  
> 收集會用到的前端函式，並分類  
> 案例分析/流程分析/頁面分析的解答  

### 8.2.2 後端函式
> SD : SDD文件  
> 收集會用到的後端函式，並分類  
> 案例分析/流程分析/頁面分析的解答  
 
## 8.3 函式庫設計
### 8.3.1 前端函式庫設計
> SD : SDD文件  
> 依照分類好的函式設計函式庫，並注意和其他函式庫關系、複用性  


> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄

### 8.3.2 後端函式庫設計
> SD : SDD文件  
> 依照分類好的函式設計函式庫，並注意和其他函式庫關系、複用性  
> 案例分析/流程分析/頁面分析的解答  

> - 設計說明
> - 重要規則
> - 模糊的地方
> - 問題點記錄

---

# 九 工作&測試項目
## 9.1 工作項目
> 將要做的事條列成工作項目，並排列執行順序

## 9.2 測試項目
> 針對工作項目、需求做測試，需注意明定測試步驟與通過標準

### 前端測試項目
> 頁面規則測試，請確定 需求、案例、頁面動態 中重要的地方都有測到  
> 請條列化或表格化  

### 後端測試項目
> 邏輯測試，請確定 需求、案例、功能流程 中重要的地方都有測到  
> 請條列化或表格化  


---

# 十、問題與討論
> 記錄要討論的問題或想法

---

# 十一、註解、參數定義、名詞定義
> 重要說明、重要規則、未做到的項目、地雷、將來要改進的項目、套件相依性、版本相依性

---

# 十二、參考資料
> 參考資料清單

二、Log

2017-09: Mars Hung編寫於HackMD
2017-11: Mars Hung修訂
2019-07-30: Mars Hung重製成md檔
2020-02-25: Mars HUng內容調整

軟體開發文件SOP

2017-09-11

Mars Hung

doc

文章閱讀量次

軟體開發文件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: 可操作的「原型」

※ 設計圖 Prototype Mockup Wireframe 的差異

軟體繪圖

使用繪圖軟體畫完圖後貼到文件中輔助說明

draw.io

whimsical

螢幕截圖

可直接從螢幕截取圖片貼到文件中輔助說明

手繪圖+拍照上傳

可將紙上繪圖、開會的白板中的文字，圖表拍照後貼到文件中輔助說明

文字敘述

部份圖表(如流程圖)也可以使用文字敘述表示，如：
點選編輯 => [View]顯示編輯彈窗 => [View-Ajax+Ctrller]載入預設資料Request+Response => [View]前端資料驗證 => [View-Ajax]送出資料Request => [Ctrller]處理&回傳結果 => [View-AjaxResp]更新訊息 => 完成編輯

我們需要文件來當反思、交接、討論、重構的依據，只需快速、示意即可，不需正式、嚴僅、精美。

SDD文件是程式設計過程的具體化，不應憑空想像。

不要貼一堆Detail的程式碼上來。

每次思考請限時

四、範本

軟體開發文件(SRS,SDD,STP)範本

五、參考

六、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 改版

Mars's Blog

軟體開發文件SOP範本

一、範本內容

軟體開發文件SOP

軟體開發文件SOP及範本

tags: `軟體開發` `開發` `軟體` `文件` `SOP`

○、說明

一、書寫原則

1.1 Why: 理解要做的事 - 記錄思考過程

1.2 How: 要怎麼做 - 記錄實現流程

1.3 What: 記錄人看得懂的資料 - 交流討論的依據

1.4 每次思考請限時

二、思考技巧：

2.1 思考方向

2.2 深入思考方式

2.3 思考焦點：

2.4 思考角度

2.5 思考深度

三、設計圖、範例圖、參考圖

3.1 設計圖種類 (擇用)

3.2 設計圖作法

軟體繪圖

螢幕截圖

手繪圖+拍照上傳

文字敘述

四、範本

五、參考

六、Log

Recents

Archives

Categories

Tags

Mars's Blog

一、範本內容

軟體開發文件SOP及範本

tags: 軟體開發 開發 軟體 文件 SOP

○、說明

一、書寫原則

1.1 Why: 理解要做的事 - 記錄思考過程

1.2 How: 要怎麼做 - 記錄實現流程

1.3 What: 記錄人看得懂的資料 - 交流討論的依據

1.4 每次思考請限時

二、思考技巧：

2.1 思考方向

2.2 深入思考方式

2.3 思考焦點：

2.4 思考角度

2.5 思考深度

三、設計圖、範例圖、參考圖

3.1 設計圖種類 (擇用)

3.2 設計圖作法

軟體繪圖

螢幕截圖

手繪圖+拍照上傳

文字敘述

四、範本

五、參考

六、Log

Recents

Archives

Categories

Tags

tags: `軟體開發` `開發` `軟體` `文件` `SOP`