有時,一張圖片可能勝過千言萬語,善用圖表可以幫助我們更請楚地表達不同的資訊及概念。
- 當講述專案進度時,甘特圖是一個強大的工具。以條形圖呈現了時間軸、里程碑和任務,讓我們可以清晰地了解專案的時間安排和進度。
- 在討論需求時,Use Case 可以幫助我們確定不同的需求和角色,並定義系統的邊界。它描述了使用者和系統之間的互動,讓我們可以更好地理解系統的功能和行為。
- 而在說明一個功能的內部運作流程時,Sequence Diagram 展示了對象之間的交互,讓我們可以視覺化地理解系統內部的運作方式。
市面上許多的圖表工具可以選擇,如 Diagrams.net (以前稱為 Draw.io) 和 Miro 等,這些工具提供了圖形化介面和各種靈活性,方便我們創建和編輯不同類型的圖表。
除了傳統的圖表工具,有一種越來越受歡迎的方式是 diagrams-as-code。將圖表以代碼的形式儲存,並使用對應的引擎將代碼渲染成圖形。可將其放在版本控制系統中,便於文件化和版本管理。
Ask chatGPT for Popularity
依照我的需求要畫 UML 及在 GitHub or GitLab 可以直接顯示,選擇有 Mermaid 和 PlantUML
大致上來說,兩套工具各有優缺:
📍環境設定
- Mermaid 基於 JavaScript,可以輕鬆在本地環境或在 GitHub 上使用。
- PlantUML 基於 Java,需要在系統中安裝 Java Runtime Environment,並配置相應的環境變數。且 GitHub 並沒有直接支援,需要透過 rendering server 來渲染圖表
📍客製化
- PlantUML 提供了豐富的自定義選項,可以根據需要調整圖表的外觀和風格。
- Mermaid的客製化選項較少,對於特定需求可能不夠使用。
📍學習曲線
- Mermaid 簡單直觀的語法,容易上手
- PlantUML 社群和資源豐富,提供了許多範例、文件和資源
📍圖表種類
各有所長,基本的圖表雙方都有,如 Sequence diagram、Usecase diagram 等,但各自也有專屬的圖表,如 PlantUML 的 JSON Data,Mermaid 的 GitGraph。
📍美觀
這可能有點主觀,但 Mermaid 生成的圖表比較現代化一點,勝出
UML Diagrams in Markdown
一般來說一個專案或 repository 都會有一份 README.md 來做為指引,要是能將圖表直接放在指引中就不會打斷觀看的體驗
以 Mermaid 來說較為簡單,GitHub 在 2022 年開始支援 Mermaid [
link],直接在 code block 中使用 Mermaid syntax 就可以了。
而 PlantUML 並不能被直接解讀,所以這時我們需要一個 rendering server,剛好 PlantUML 有提供了一個 proxy server: http://www.plantuml.com/plantuml/proxy?src=<resource URL> ,再搭配已 commit 到 github 上的 plantmul 檔,就可以直接在 markdown 中顯示了