Bài 53 — Confluence Macros nâng cao

Mở đầu — vì sao bài này quan trọng

Nếu bạn đã đi qua các bài trước về Confluence — Spaces, Pages, Templates, và đặc biệt là Bài 15 về các macro cơ bản như Status, Info Panels, Page Properties — thì bạn đã nắm được "bộ công cụ phổ thông" để viết tài liệu. Nhưng sự thật là phần lớn BA dừng lại ở đó. Họ viết BRD, viết meeting note, chèn vài cái bảng và một panel màu xanh, rồi coi như xong.

Vấn đề là: tài liệu của một BA giỏi không chỉ để "đọc" — nó phải sống. Một trang Confluence tốt phải tự cập nhật khi dữ liệu thay đổi, phải biết nhắc đúng người vào đúng lúc, phải tổng hợp thông tin từ hàng chục trang con mà không cần ai copy-paste thủ công, và phải kết nối ngữ cảnh giữa con người với nội dung. Đó chính là lĩnh vực của macro nâng cao.

Trong bài này, chúng ta sẽ đi sâu vào ba nhóm macro mà một BA chuyên nghiệp thực sự dùng để biến tài liệu tĩnh thành tài liệu động: macro nhắc người dùng (user mentions & user profile), macro tổng hợp nội dung (Content by Label, Children Display, Excerpt/Excerpt Include), và cách nhúng & recap các macro JIRA ngay trong tài liệu để bức tranh dự án luôn nhất quán giữa hai công cụ. Mục tiêu cuối: bạn rời bài học với khả năng dựng được một trang "trung tâm điều phối" mà các bên liên quan chỉ cần mở ra là thấy mọi thứ mới nhất.

Khái niệm cốt lõi

Macro vs Markup — bạn đang nói chuyện với cái gì?

Trước hết cần phân biệt rõ. Trong Confluence Cloud hiện đại (editor mới), bạn chèn macro bằng cách gõ dấu / rồi chọn tên macro, hoặc gõ @ để mention người dùng. Nhưng đằng sau giao diện đó, mỗi macro vẫn là một khối có cú pháp riêng. Trong Confluence Server/Data Center (và một số ngữ cảnh wiki markup cũ), bạn sẽ thấy cú pháp dạng {tên-macro:tham-số=giá-trị}. Khi tài liệu đề cập {user-profile:user=username}, đó chính là dạng markup của macro User Profile. Hiểu cả hai dạng giúp bạn không bối rối khi nhảy giữa các phiên bản Confluence khác nhau — điều rất hay xảy ra ở doanh nghiệp Việt Nam vẫn còn dùng Server bên cạnh Cloud.

Nhóm 1 — Macro liên quan đến con người

User Mention (@) không đơn thuần là gõ tên cho đẹp. Khi bạn gõ @ và chọn một người trong phần thân (body) của trang hoặc trong comment, Confluence làm ba việc cùng lúc: (1) tạo một liên kết tự động tới hồ sơ người đó, (2) gửi thông báo (notification) cho họ rằng họ vừa được nhắc tới, và (3) ghi nhận họ như một người có liên quan tới nội dung. Đây là cơ chế "auto-link, notify" cực kỳ quan trọng — nó biến một câu như "anh Tuấn sẽ review phần Non-functional Requirements" thành một hành động thực sự đẩy thông báo tới đúng người, thay vì hy vọng họ tình cờ đọc được.

User Profile macro ({user-profile:user=username}) thì khác. Thay vì chỉ là một cái link tên, nó nhúng nguyên một thẻ hồ sơ (user card) ngay trong trang: ảnh đại diện, chức danh, phòng ban, thông tin liên hệ. Macro này không gửi thông báo (vì nó chỉ là hiển thị thông tin, không phải mention), nhưng nó cực kỳ hữu ích khi bạn muốn người đọc biết ngay "ai là chủ sở hữu của tài liệu này" hoặc "đầu mối liên hệ cho module này là ai". Tham số quan trọng nhất là user — bạn truyền vào username (hoặc account ID trên Cloud). Đây là điểm phân biệt cốt lõi: mention để gọi, user-profile để giới thiệu.

Nhóm 2 — Macro tổng hợp nội dung động

Đây là nhóm tạo ra giá trị "tự cập nhật". Ba macro chủ lực:

• Content by Label: liệt kê tự động mọi trang có gắn một nhãn (label) nhất định. Bạn không cần liệt kê thủ công các BRD — chỉ cần gắn nhãn brd cho mọi BRD, rồi đặt một macro Content by Label với label brd, danh sách sẽ tự dài ra mỗi khi có tài liệu mới.
• Children Display: hiển thị tất cả trang con của trang hiện tại (hoặc một trang chỉ định). Lý tưởng cho cấu trúc "trang mẹ là module, trang con là từng user story".
• Excerpt + Excerpt Include: bạn đánh dấu một đoạn nội dung "trích yếu" trên trang A bằng macro Excerpt, rồi trên trang B dùng Excerpt Include để kéo đoạn đó về. Khi trang A sửa, trang B tự đổi theo. Đây là "single source of truth" ở cấp đoạn văn — vô cùng mạnh cho BA cần đảm bảo định nghĩa thuật ngữ chỉ tồn tại ở một nơi.

Nhóm 3 — Recap macro JIRA trong Confluence

Bài 16 đã nói về liên kết JIRA & Confluence ở cấp tổng thể; ở đây ta recap đúng phần "dùng macro JIRA như một macro nâng cao trong tài liệu". JIRA Issues macro cho phép bạn nhúng một issue đơn, một danh sách issue theo JQL, hoặc thậm chí một bảng đếm số lượng. Điểm nâng cao mà nhiều người bỏ qua: macro này hiển thị trạng thái thời gian thực — nếu một story chuyển từ "In Progress" sang "Done" trong JIRA, bảng trong BRD của bạn đổi màu theo ngay, không cần sửa tay. Kết hợp một JQL chuẩn (xem lại Bài 7–8) với macro này, bạn có một "live tracker" nhúng thẳng vào tài liệu nghiệp vụ.

Tình huống thực tế

Tình huống 1 — Tiki và trang "Module Owner" tự giới thiệu

Tại một nhóm Product của một sàn thương mại điện tử lớn như Tiki, dự án "Checkout v2" có 6 module, mỗi module một BA phụ trách. Trước đây, mỗi khi dev hoặc QA mở trang BRD của một module, họ không biết hỏi ai khi gặp thắc mắc — phải đi nhắn vòng vòng trong Slack. Chị Lan, BA Lead, quyết định chuẩn hóa: ở đầu mỗi trang module, chị chèn {user-profile:user=...} của BA phụ trách. Giờ ai mở trang "Payment Gateway" là thấy ngay thẻ hồ sơ của anh Khánh — ảnh, chức danh "Senior BA", phòng "Payments", kèm nút liên hệ.

Diễn giải: thời gian "tìm đúng người để hỏi" giảm rõ rệt. Quan trọng hơn, khi anh Khánh nghỉ và bàn giao cho người khác, chị Lan chỉ cần đổi username trong một macro — toàn bộ trang tự cập nhật đầu mối. Bài học: dùng User Profile macro cho thông tin "ai sở hữu cái gì", đừng gõ tên cứng vào văn bản vì tên cứng sẽ lỗi thời và không click được.

Tình huống 2 — Một fintech ở TP.HCM và "Live BRD" với macro JIRA

Một công ty fintech tầm trung tại TP.HCM (khoảng 40 dev, dùng JIRA + Confluence Cloud) gặp đúng nỗi đau kinh điển: BRD viết trên Confluence liệt kê 28 user story, nhưng tiến độ thật nằm trong JIRA. Mỗi tuần họp với khách hàng, BA phải mở hai cửa sổ và đối chiếu thủ công xem story nào đã xong — và thường xuyên báo cáo sai vì số liệu trong BRD đã cũ 3 ngày.

Anh Dũng, BA của dự án, chèn vào cuối BRD một JIRA Issues macro với JQL project = FIN AND fixVersion = "Release 3.2" ORDER BY status. Macro hiển thị bảng 28 issue kèm cột Status đổi màu theo thời gian thực. Thêm một macro JIRA dạng "count" ở phần tóm tắt: "Hoàn thành: 19/28". Từ đó, mỗi buổi họp khách chỉ cần mở đúng một trang BRD, mọi con số đã tự đồng bộ với JIRA.

Diễn giải: sai số báo cáo về 0, vì không còn bước copy thủ công. Bài học: với BA, JIRA Issues macro không phải đồ trang trí — nó là cách biến tài liệu tĩnh thành dashboard nhẹ. Hãy luôn dùng JQL có bộ lọc rõ ràng (project + fixVersion/sprint) để tránh kéo về cả nghìn issue làm trang nặng.

Tình huống 3 — Agency phần mềm và "Glossary một nguồn" bằng Excerpt Include

Một agency outsourcing ở Đà Nẵng làm dự án cho khách Singapore có một rắc rối: thuật ngữ nghiệp vụ "Active Merchant" được định nghĩa lại ở 7 trang BRD khác nhau, và sau vài tháng, các định nghĩa lệch nhau khiến dev hiểu sai phạm vi. Mỗi lần khách chỉnh định nghĩa, BA phải sửa 7 chỗ — và luôn sót.

Giải pháp: tạo một trang "Glossary" duy nhất. Trên trang đó, định nghĩa "Active Merchant" được bọc trong một Excerpt macro. Ở 7 trang BRD, BA thay đoạn định nghĩa cũ bằng Excerpt Include trỏ về trang Glossary. Từ đó, định nghĩa chỉ tồn tại ở một nơi; sửa Glossary là cả 7 trang đổi theo.

Diễn giải: loại bỏ hoàn toàn rủi ro "lệch định nghĩa". Bài học: bất cứ nội dung nào lặp lại ở nhiều trang — định nghĩa, điều khoản pháp lý, mô tả API chung — hãy dùng Excerpt/Excerpt Include để giữ một nguồn sự thật duy nhất.

Hướng dẫn từng bước

Bước 1 — Nhúng thẻ hồ sơ người dùng (User Profile). Trong editor mới: gõ /User Profile, chọn macro, rồi nhập tên hoặc account của người cần hiển thị. Trong dạng markup (Server/DC): chèn {user-profile:user=khanh.nguyen}. Lưu ý phân biệt với mention: nếu bạn chỉ muốn gọi và thông báo cho ai đó, hãy gõ @khanh ngay trong câu văn — nó tạo auto-link và gửi notification. Nếu bạn muốn trưng bày một thẻ hồ sơ đầy đủ, dùng User Profile macro.

Bước 2 — Dựng danh sách tự động bằng Content by Label. Gõ /Content by Label. Trong cấu hình, nhập label cần gom (ví dụ brd), giới hạn phạm vi theo Space nếu cần, chọn cách hiển thị (list hay table), và đặt số lượng tối đa. Lưu trang. Từ giờ, mọi trang gắn label brd sẽ tự xuất hiện ở đây.

Bước 3 — Hiển thị trang con bằng Children Display. Trên trang mẹ (ví dụ trang "Module: Checkout"), gõ /Children Display. Để mặc định nếu muốn liệt kê con của chính trang hiện tại, hoặc chỉ định trang gốc khác. Bật tùy chọn hiển thị theo cây (depth) nếu cấu trúc nhiều tầng.

Bước 4 — Tạo nguồn sự thật duy nhất bằng Excerpt + Excerpt Include. Trên trang nguồn: bọc đoạn cần tái sử dụng bằng /Excerpt. Trên trang đích: gõ /Excerpt Include, chọn trang nguồn. Nội dung sẽ được kéo về và tự đồng bộ khi nguồn thay đổi.

Bước 5 — Nhúng live data từ JIRA. Gõ /JIRA (hoặc /Jira Issues). Dán một issue key đơn (ví dụ FIN-204) để nhúng một issue, hoặc chuyển sang chế độ "Search" và dán JQL để nhúng danh sách. Chọn các cột cần hiển thị (Key, Summary, Status, Assignee). Nếu chỉ cần con số, chọn kiểu hiển thị "Total count".

Bước 6 — Đóng gói thành template. Khi đã có bố cục ưng ý (User Profile owner ở đầu + JIRA tracker ở cuối + Children Display ở giữa), lưu thành Page Template để cả nhóm tái sử dụng — đây là cách nhân rộng chuẩn macro nâng cao cho toàn team.

Lỗi thường gặp & mẹo

Lỗi 1 — Nhầm User Profile với Mention. Rất nhiều BA dùng User Profile macro rồi thắc mắc tại sao người được nhắc không nhận thông báo. Nhớ: User Profile chỉ hiển thị, không notify. Muốn thông báo, phải dùng @mention trong thân bài hoặc comment.

Lỗi 2 — JQL trong JIRA macro quá rộng. Dán JQL kiểu project = FIN không có bộ lọc version/sprint sẽ kéo về hàng trăm issue, làm trang tải chậm và khó đọc. Mẹo: luôn ràng buộc thêm fixVersion, sprint, hoặc status để giới hạn.

Lỗi 3 — Lạm dụng macro tổng hợp khiến trang nặng. Nhồi 5–6 Content by Label và Children Display vào một trang sẽ khiến mỗi lần mở trang phải truy vấn rất nhiều. Mẹo: tách thành các trang chuyên biệt, mỗi trang một mục đích.

Lỗi 4 — Quên rằng macro phụ thuộc dữ liệu nguồn. Nếu bạn xóa label hoặc đổi cấu trúc trang con, Content by Label và Children Display sẽ rỗng mà không báo lỗi rõ ràng. Mẹo: chuẩn hóa quy ước đặt label ngay từ đầu dự án và ghi vào trang hướng dẫn của Space.

Lỗi 5 — Excerpt trỏ vòng hoặc trỏ tới trang đã xóa. Khi trang nguồn bị xóa/đổi tên, Excerpt Include sẽ hỏng. Mẹo: đặt mọi Excerpt dùng chung trong một trang "Glossary/Shared Content" được bảo vệ quyền chỉnh sửa, tránh ai đó vô tình xóa.

Mẹo chung: Confluence Cloud và Server có thể khác nhau về danh sách macro khả dụng. Trước khi xây template cho cả công ty, hãy kiểm tra phiên bản đang dùng để chắc chắn macro bạn chọn tồn tại trên mọi instance.

Bài tập thực hành

• Tạo một trang "Project Hub" cho một dự án giả định của bạn. Ở đầu trang, chèn User Profile macro giới thiệu chính bạn là BA owner. Ngay dưới đó, viết một câu có @mention một đồng nghiệp và quan sát họ có nhận thông báo không.
• Gắn label story cho ít nhất 3 trang con, rồi đặt một Content by Label macro để chúng tự liệt kê. Thêm một trang mới có cùng label và kiểm tra xem nó tự xuất hiện chưa.
• Tạo trang "Glossary", định nghĩa 1 thuật ngữ trong một Excerpt, rồi dùng Excerpt Include kéo nó về trang Hub. Sửa định nghĩa ở Glossary và xác nhận trang Hub đổi theo.
• Nhúng một JIRA Issues macro bằng JQL có ràng buộc (ví dụ project = X AND sprint in openSprints()). So sánh trải nghiệm với việc liệt kê issue thủ công.
• Lưu toàn bộ bố cục trên thành một Page Template và viết 2–3 dòng hướng dẫn cách dùng cho đồng đội.

Tóm tắt

Macro nâng cao trong Confluence là ranh giới giữa một BA "viết tài liệu" và một BA "thiết kế hệ thống tri thức". Ba trụ cột cần nhớ: macro con người (mention để gọi-và-thông-báo, {user-profile:user=...} để giới thiệu đầu mối mà không notify); macro tổng hợp động (Content by Label, Children Display, Excerpt/Excerpt Include) để tài liệu tự cập nhật và giữ một nguồn sự thật duy nhất; và macro JIRA nhúng để biến BRD tĩnh thành live tracker đồng bộ thời gian thực với JIRA. Ba tình huống từ Tiki, fintech TP.HCM và agency Đà Nẵng cho thấy cùng một quy luật: ở đâu còn copy-paste thủ công, ở đó còn sai sót và lãng phí — và macro nâng cao chính là công cụ để xóa bỏ điều đó. Hãy bắt đầu bằng cách dựng một "Project Hub" cho dự án thật của bạn, rồi đóng gói nó thành template để nhân rộng chuẩn cho cả team.