Mermaid

Bạn gõ mấy dòng chữ, GitHub hay Notion tự vẽ ra sơ đồ. Không phải mở draw.io, không có file .drawio nằm chết trong thư mục chung, và quan trọng nhất: sơ đồ nằm ngay trong tài liệu, sửa nó bằng cách sửa chữ.

Với Mermaid, sơ đồ là văn bản. Nghĩa là nó vào được Git, so sánh được hai phiên bản, và review được như review code.

Ba loại BA dùng nhiều nhất

Lưu đồ nghiệp vụ:

flowchart TD
    S([Bắt đầu]) --> A[Khách tạo đơn]
    A --> B{Còn hàng?}
    B -->|Có| C[Giữ hàng 15 phút]
    B -->|Không| D[Gợi ý sản phẩm thay thế]
    C --> E{Thanh toán trong 15 phút?}
    E -->|Có| F[Xác nhận đơn]
    E -->|Không| G[Nhả hàng, huỷ giữ chỗ]
    D --> Z([Kết thúc])
    F --> Z
    G --> Z

Luồng tích hợp:

sequenceDiagram
    participant App as App khach
    participant BE as Backend
    participant PG as Cong thanh toan
    App->>BE: POST /orders
    BE->>PG: Tao yeu cau thanh toan
    PG-->>BE: payment_url
    BE-->>App: payment_url
    PG-)BE: Callback ket qua (bat dong bo)
    BE-)App: Cap nhat trang thai don

Mô hình dữ liệu:

erDiagram
    KHACH_HANG ||--o{ DON_HANG : "dat"
    DON_HANG ||--|{ CHI_TIET_DON : "gom"
    SAN_PHAM ||--o{ CHI_TIET_DON : "xuat hien trong"

Ba khối trên dán thẳng vào file .md trên GitHub là ra hình. Nhớ ghi chữ mermaid ngay sau ba dấu backtick mở — thiếu chữ đó thì GitHub chỉ hiện ra một khối chữ chứ không vẽ.

Cú pháp học một buổi trưa là đủ dùng, chỉ cần để ý mấy ký hiệu mũi tên ở khối sequence: ->> là gọi đồng bộ, -->> là giá trị trả về, còn -) mới là bắn đi bất đồng bộ rồi đi tiếp. Gõ nhầm một ký tự là sơ đồ nói ngược lại ý bạn viết trong chú thích.

Chỗ nào render sẵn

GitHub và GitLab render trong file markdown, cả trong issue và pull request. Notion có block /code chọn ngôn ngữ Mermaid. Obsidian, VS Code (qua extension), Azure DevOps wiki đều chạy. Confluence Cloud thì tuỳ instance, nhiều nơi phải cài app riêng, nên hỏi admin trước khi hứa với team.

Điểm cần biết: mỗi nền tảng chạy một phiên bản Mermaid khác nhau. Cú pháp mới viết ở VS Code chạy ngon, dán lên wiki công ty có thể báo lỗi cú pháp. Gặp là bình thường, hạ về cú pháp cơ bản là xong.

Nhờ AI sinh rồi ngồi sửa

Cách nhiều BA đang làm, và làm được thật: dán biên bản họp hoặc phần mô tả nghiệp vụ vào một trợ lý AI, bảo nó xuất ra flowchart Mermaid, dán vào Confluence, rồi ngồi sửa lại.

Phần AI làm tốt là dựng khung và viết đúng cú pháp, đỡ hẳn công gõ. Phần nó bịa là điều kiện rẽ nhánh và nhánh lỗi. Nó sẽ tự nghĩ ra "nếu không đủ điều kiện thì báo lỗi", trong khi nghiệp vụ thật là chuyển sang duyệt tay ở phòng rủi ro. Nên coi bản AI sinh ra là bản nháp đầu, không bao giờ là bản gửi khách.

Được cái nhanh. Một cái flowchart mười lăm ô, nhờ AI dựng khung rồi ngồi sửa, thường xong trong lúc chờ họp; gõ tay từ đầu thì phải ngồi nghiêm túc một lúc. Nhưng đừng mừng vội. Phần tiết kiệm được là phần gõ; phần hiểu nghiệp vụ vẫn nằm nguyên đấy, và đó mới là phần sai đắt tiền.

Ví dụ thực tế

Chiều thứ Sáu, khách đổi chính sách hoàn tiền cho đơn giao một phần. Tài liệu phải cập nhật trước sáng thứ Hai.

Đây là module hoàn tiền của một sàn thương mại điện tử nội địa, chừng 870 yêu cầu hoàn một tuần. Tài liệu nằm hết trên Confluence — instance của công ty có cài sẵn app render Mermaid — mỗi trang một khối flowchart TD gói gọn luồng của trang đó. Mình sửa đúng ba dòng chữ trong khối code, lưu, xong trước giờ về. Trước đó cùng việc ấy phải mở file .drawio, sửa, xuất PNG, tải lên, thay ảnh cũ, và tuần sau vẫn có người mở nhầm ảnh bản trước.

Nhược điểm phải biết trước

• Bố cục do máy tự sắp. Muốn sơ đồ nằm đúng ý mình thì vật vã, đôi khi phải chèn node ẩn.
• Độ phủ UML mỏng: class và state diagram có nhưng sơ sài, component hay deployment thì không.
• Trên ba mươi node là bắt đầu rối mắt.
• Không hợp để in ra khổ lớn dán tường.

Nếu tài liệu của team đang nằm trên Git hoặc Confluence, cứ bắt đầu bằng Mermaid. Khi nào chật thì hẵng tính tới PlantUML hoặc draw.io.