文件

2019/08/05 (新增連結)
2023/03/11 (更新文件範本)
2023/03/18 (調整內容)
2023/03/19 (微調內容)
2023/05/02 (新增sprint進度報告範例)
2023/05/13 (新增firestore範例)
2024/02/27 (文件與進度報告合併)
2024/02/28 (文件內容更新)
2025/04/19 (文件內容更新)
2025/05/17 (補充第四章內容說明)
2025/05/18 (新增文件結構說明)

文件結構說明

開發團隊利用文件來記錄使用者的需求以及系統的設計，應該在開發系統之前，先透過整理文件形成共識，再去開發系統。過去的瀑布式開發方法論是先完成第一章，根據第一章內容去完成第二章內容，再根據第二章內容去完成第三章內容，在結案時，完成第四章內容。

運用敏捷的開發方法論時，做法有點不同，會先完成第一章，在每個sprint完成第二章及第三章的對應內容，在sprint中，先確認user story確認所需要的邏輯與資料，調整資料庫設計，再去設計畫面，根據文件內容去開發系統。

文件的章節之間是有關連的:

• 第一章系統描述的主是讓讀者可以很快地了解使用者情境、問題與解決方案

  • 發展背景描述的是使用者情境，透過了解使用者情境，簡述使用者的背景與現有的系統，簡述背景知識中的相關系統或競品

  • 發展動機則是描述出使用者的痛點 (或未能滿足的價值)

  • 發展目的則是描述問題與解決方案之間的關聯

  • 系統範圍則是進一步說明解決方案

  • 發展背景描述相關系統或競品

    • 更完整的說明在發展背景中所提到的相關系統或競品

  • 系統限制則是描述無法滿足的需求以及無法滿足的原因

• 第二章軟體需求規格

  • 功能需求是透過User story的格式進一步描述系統範圍中所描述的解決方案

    • 使用者角色說明描述有哪些使用者以及主要情境

    • 使用者故事對應描述user story之間的邏輯結構以及優先順序

    • 使用者故事卡描述使用者、需求及價值並透過接受條件描述邏輯細節及所需要的輸入、輸出資料

• 第三章軟體設計規格

  • 資料庫設計是去描述所需要的資料庫設計

  • 介面設計則是去描述畫面設計

• 第四章系統專題實作檢討

  • 發展中遭遇到問題、困難與解決方法整理整個開發過程中遇到的問題、困難與解決方法

  • 系統優缺點(SWOT)評估進行開發後的SWOT評估

  • 發展心得記錄個人、團隊的發展心得

  • 未來展望紀錄未來的可能開發方向

    • 系統限制是事先的評估，未來展望則是開發後的評估

補充

一般業界的文件要比我們的文件要求還要完整:

• How to write good software technical documentation 

  • Code documentation

  • Functions & Methods header comments

  • Product documentation

  • Technical schemas

    • Database Schemas

    • Software Architecture Schemas

    • Sequence Diagram

  • Technical decision logs

其實，開發者都不喜歡寫文件，有些人則認為可以透過寫註解來代替文件，但是，文件還是不可或缺

• Self-documenting code is (mostly) nonsense

  • Step 1: Actually write some documentation

  • Step 2: Make some diagrams

  • Step 3: Use Ubiquitous Language to help the naming of your classes and actions

  • Step 4: Just add some comments

文件審查項目及常見問題

2022/03/20 (新增內容)
2022/06/01 (新增內容)
2022/06/06 (新增內容)
2022/06/14 (新增內容)
2023/03/18 (調整內容)
2024/05/19 (補充常見問題)
2025/04/28 (標示常見問題)
2025/05/17 (補充第四章說明)

• 文件範本

• 第一章 系統描述

  • 常見問題: 發展背景與動機、系統發展目的、系統範圍、背景知識、系統限制之間都沒有關連

    • 今年特別嚴重

  • 發展背景與動機

    • 發展背景

      • 針對組織發展系統的組別，發展背景應描述與系統相關的組織背景，如:簡述目前存在的相關系統、類似系統或者相關競品 (競爭對手的產品)

      • 針對特定使用者發展系統的組別，發展動機正確描述目標使用者以及相關背景，如:簡述目前存在的相關系統

      • 常見問題: 

        • 未說明組織背景 (目標組織簡介) 或目標使用者以及相關背景 (目標使用者簡介)

        • 未簡述目前存在的相關系統或者相關競品 (競爭對手的產品)

        • 未提及知識背景中提及的相關系統

    • 發展動機正確描述目前使用者所面臨的問題或現存系統(如:競品)的缺點

      • 常見問題: 未描述目前使用者所面臨的問題或現存系統(如:競品)的缺點，或描述不完整

  • 系統發展目的

    • 系統發展目的根據發展動機，簡單描述系統的功能性需求

      • 針對發展動機所提到的問題，簡單說明如何解決這些問題

      • 常見問題: 目的與動機不一致

        • 動機所提的問題在目的裡沒有提到解決方案，或者目的又列出新的問題

    • 系統發展目的可簡單描述系統的非功能性需求

    • 問題與解決方案對應表

      • 請整理發展目的所提到的問題與解決方案

    • 常見問題: 

      • 目的與動機不一致

      • 問題與解決方案對應表裡的問題與解決方案跟發展目的所敘述內容不一致

      • 未思考非功能性需求

  • 系統範圍

    • 根據使用者的情境盤點任務，針對任務盤點功能性需求

      • 需求不一定都列在上述的解決方案中，但是沒有這些基礎功能無法提供解決方案

    • 盤點發展目的中的每一項解決方案，是否都涵蓋在系統範圍，並更進一步描述功能性需求

      • 目的在於可以讓讀者在閱讀需求規格(第二章)之前對系統的功能可以有一個概略性的了解

    • 系統範圍只包含將開發之需求 (不在此次範圍內的需求，應列在系統限制)

      • 常見問題: 

        • 系統範圍未包含應有的基本功能性需求

        • 系統範圍未完全包含系統目的中提及的解決方案

        • 系統範圍包括了非功能性需求 

  • 背景知識

    • 應詳細描述與系統相關背景知識，如:在發展背景中提到的現有系統、其他相關系統或競品

      • 常見問題:背景知識與發展背景不一致

    • 對於本系統相關之新概念與新技術，應重點描述與系統相關或重要之背景知識 (不需介紹已經算是基本常識的內容，如:internet、電子商務、java等)

      • 常見問題:背景知識與發展背景不一致

  • 系統限制(可行性分析)

    • 系統限制描述未包含在系統範圍之使用者的需求 (不需要列出不是使用者需求的限制)，說明一下

      • 這些需求對使用者(如:消費者)的重要性

      • 解釋需求未包含在系統範圍的原因

    • 常見問題: 

      • 並未依照現有問題去思考系統限制

      • 前面提到的問題後來沒有提出解決方案，也沒有列入系統限制

      • 前面提出的解決方案後來沒有列入系統範圍，也沒有列入系統限制

• 第二章 軟體需求規格

  • 使用者角色說明

    • 描述使用者以及使用情境

    • 常見的問題

      • 與使用者故事裡的角色不一致

  • 使用者故事對應 

    • 常見的問題

      • 不應該從開發者的角度思考Epic、User Story，應該以user的觀點思考，如果，使用者相關的user story分散在不同的Epic，也應該要標明對應的使用者

      • 並沒有分Epic、User Story

        • 通常的問題在於沒有去思考細節

      • 並沒有深思這些使用者故事的優先順序

      • 與系統範圍內容不一致

      • Epic或User Story過度分割

        • Epic下如果只有一個或兩個User Story，就應該與其他Epic合併

  • 使用者故事卡

    • Epic、User Story的名稱應該是動詞

    • 使用者故事應該清楚的列出使用者 (I am)

    • 使用者故事應該清楚的描述使用者的需求 (I want)

      • 說明如何解決問題或如何提供價值

    • 使用者故事應該清楚的描述需求對使用者的價值 (So that)

      • 解決了使用者的甚麼問題或提供使用者的價值

      • 或者這個user story會透過哪些/個user story解決了使用者的甚麼問題或提供使用者的價值

    • 常犯的問題:

      • 沒有清楚的定義使用者

      • 需求跟價值內容一樣，並沒有深思這個user story的真正價值

        • 需求: 我想要可以看到註冊的資料

        • 價值: 因此系統可以看到註冊者的會員資訊的資訊

          • 管理者需要這個功能嗎? 為什麼?

      • 需求跟價值內容相反，把需求當價值、把價值當需求

      • User story的名稱不是動詞

    • 驗收條件

      • Epic採列點式接受/驗收條件 ** 更進一步的說明使用者的需求(I want) **

        • 在epic中要利用驗收條件描述所包含的user story之間的關係

          • 互相獨立 (不同情境) 還是互相依賴 (有先後順序)

          • 當這些user story的關係很複雜時，也可利用活動圖說明user story之間的關係

        • 常見問題: 列出user story並沒有說明user story之間的關係

      • User Story採情境式接受/驗收條件 ** 更進一步的說明使用者的需求(I want) **

        • 在user story中要利用驗收條件描述完成這個user story的條件

          • 驗收條件主要重點在於輸出及輸入資料的確認，不需要詳述使用者介面操作過程，不需要描述點了哪些按鈕，操作過程的部分在介面設計時描述

        • 情境(Scenario)

          • Given (前提或條件)

            • 進入的條件或者是前一(或幾)個user story

          • When (When I enter or do ... / 使用者採取的動作)

          • Then (Then I will see or get ... /使用者得到的回饋)

            • 通常是計算的結果或檢查輸入的結果(告知使用者是否有問題)

        • 常犯的問題:

          • 在user story中，並未詳述所需要的資料

            • 例如: 只敘述「消費者輸入註冊資料」，但是，並沒有說明哪些資料(如:帳號、密碼....)

          • Given、When、Then沒分清楚

            • Given不應該是使用者採取的動作

            • When不應該是條件

            • Then不應該是採取的動作

          • Scenario沒有想清楚

            • 例如: 只敘述「當消費者無法登入」，但是，並沒有說明無法登入的規則

          • Given裡面不應該提到這個user story裡的步驟

            • Given是前置動作，也就是執行這個user story前的相關user story

            • When與Then才是這個user story裡的步驟

          • When裡面不應該提到其他的user story

            • 其他的user story應該在Given

            • user story的動作中包含其他user story，就無法獨立驗收

          • 在Then裡通常不會描述後續的user story的步驟

            • Then的目的主要是驗證這個user story是否正確的完成，通常不包含其他user story

              • 如果包含其他的User Story就變成也要驗證下個user story的這些步驟是否完成。通常不在Then裡面說明後續的user story，而是在後續的user story中利用given描述前置的user story。

              • 例如: 在「登入」(1.7)中列「註冊」(1.6)功能為Given。

                • Given 購買者已經註冊會員 (1.6)

                • When 購買者輸入帳號、密碼

                • Then 購買者完成登入，呈現已登入狀態

            • 如果Then包含其他的user story，通常該user story要先完成，而且可透過該user story去驗證這個user story已完成

              • 例如: 在「刪除資料」的User Story中，可透過瀏覽資料的user story確認資料已刪除，或者透過「登入」確認「註冊」功能已完成。

• 第三章 軟體設計規格

  • 資料庫設計

    • 明列所使用之資料庫，如:mySQL、Firestore

    • 關聯式資料庫 (RDBMS)

      • 關連一覽表列出資料表編號、資料表名稱、說明

        • 資料表名稱最好有統一的命名規則

      • 關連結構列出資料表編號、資料表名稱、欄位編號、欄位名稱、型態、長度、說明

        • 欄位名稱最好有統一的命名規則

      • 關連結構正確標示Primary Key (PK)及Foreign Key (FK)

        • FK應標示對應的資料表及欄位

      • 欄位型態及長度皆合理

      • 所有資料表都已為最適之正規化設計 (如：第三正規化)，如果沒有，也應該有解釋

      • 資料表之間無不合理的關連（如：沒必要的一對一關連或多對多關連）

      • 關連一覽表與實際資料表一致 (驗收時檢查)

      • 關連結構實際資料表一致 (驗收時檢查)

    • NO SQL

      • 應清楚解釋資料結構: 有多少種物件，每種物件的資料結構，可利用JSON舉例說明

  • 介面設計

    • 介面藍圖一覽表中的介面與使用者故事一致 (未遺漏任何使用者故事)

    • 介面藍圖(畫面)說明清楚說明畫面上的元件所相對應的動作

    • 介面藍圖(畫面)說明清楚說明畫面上的元件所相對應的介面藍圖(畫面)

    • 當這些user story的關係很複雜時，可利用狀態圖說明使用者介面藍圖間的關係

    • 常見問題:

      • 只畫了畫面，都沒有解釋畫面上的元件所對應的動作，或沒有利用介面編號標示相關的畫面

        • 例如，功能導覽列每個選項的對應畫面、登入之後會到哪個畫面

      • 畫面流程不完整，有些畫面之間的關係被遺漏

      • 介面編號應該是介面藍圖一覽表中的編號而不是使用者故事編號，介面說明中應該註明畫面編號而非使用者故事編號

      • 把同一個user story的不同畫面放在一起

        • 每個介面藍圖都應該獨立

      • 把同一個畫面的不同狀態放在一起

        • 每個介面藍圖都應該獨立

          • 例如，應該把登入前、登入後的首頁分開，並在畫面說明中描述兩個首頁間的關係

      • 不同畫面用同個編號

        • 基本上應該一個畫面一個編號

      • 同一畫面分成兩個編號

        • 同一畫面就算太長，分多次截圖，也是一個畫面

  • 資源需求

    • 開發系統所需要的人力、軟體、硬體及對應的經費預估

      • 人力

        • 總工時*時薪

      • 軟體: 作業系統、資料庫、開發環境、程式語言

      • 硬體: 網路、伺服器、個人電腦、手機

    • 營運系統所需要的人力、軟體、硬體及對應的前三年經費預估，營運期間的資源跟開發期間的資源通常不會完全一樣，例如，維運期間需要的人力，不會是只有開發人員，營運期間也不需要所有的開發人力

      • 人力

        • 預估工時*時薪

      • 軟體: 作業系統、資料庫、開發環境、程式語言

      • 硬體: 網路、伺服器、個人電腦、手機

    • 常見問題:

      • 軟硬體成本都是0，都是只是列開發者既有的電腦，應估算上線後所需要的軟硬體成本

        • 例如:專用的伺服器成本或放到雲端(如:AWS、GCE)的預估費用

      • 人力隨便估算，並沒有說明為何需要這麼多人力

• 第四章 系統專題實作檢討

  • 發展中遭遇到問題、困難與解決方法

    • 專題文件中並沒有進度報告，所以，可以統整scrum retrospective的內容

  • 系統優缺點(SWOT)評估

    • 優勢（Strengths）：企業或項目相對於其他企業或專案的優勢，這些劣勢會使得企業或專案處於有利地位

    • 劣勢（Weaknesses）：使企業或項目相對於其他企業或專案的劣勢，這些劣勢會使得企業或專案處於不利地位

    • 機會（Opportunities）：企業或專案可以利用的、能夠為其帶來優勢的外部環境因素

    • 威脅（Threats）：可能為企業或專案帶來麻煩的外部環境因素

  • 發展心得

    • 統整大家的心得

  • 未來展望

    • 系統限制是事先的評估，未來展望則是開發後的評估

    • 有些系統限制是因為在時間的限制下無法達成，就可以寫在未來展望 (以專題文件而言就是學弟妹可以參考的專題方向)

• 分工貢獻

  • 希望大家去紀錄工時，主要是希望大家未來可以利用這些數據，作為下個sprint及專題時人力估算的參考

  • 老師的評分將參考貢獻度的百分比

    • 貢獻度不一定依據總工時去計算，因為有些同學可能不用花太多時間就可以有很多貢獻，有些同學雖然花很多時間，但不必然有貢獻

    • 如果發現有虛報貢獻度之可能性，老師會要求驗收以確認貢獻度