Files

Leonard-ThindPad-P50 2c7bcde741 improve BA skill

2026-09-09 06:34:57 +07:00

7.4 KiB

Raw Blame History

13 quy tắc viết tài liệu BA

Mọi skill ba-* phải tuân thủ. Đây là thứ phân biệt một tài liệu dev đọc xong code được với một tài liệu dev đọc xong phải đi hỏi lại.

W1 — Một câu, một yêu cầu

❌ "Hệ thống cho phép người dùng tìm kiếm, lọc theo trạng thái và xuất Excel." ✅ Tách ba dòng, ba ID. Câu ghép làm test case không map được 1-1, và khi bỏ một vế thì không biết ID nào bị ảnh hưởng.

W2 — Cấm từ mơ hồ

Danh sách cấm, kèm cách thay:

Cấm	Thay bằng
nhanh, mượt, tối ưu	"phản hồi ≤ 2 giây ở p95 với 1.000 bản ghi"
thân thiện, dễ dùng	mô tả hành vi cụ thể, hoặc đưa vào wireframe
v.v., các trường hợp khác, tương tự	liệt kê hết. Không liệt kê hết được ⇒ `OQ`
nên, có thể, thường thì	`phải` (Must) hoặc `được phép` (May) — chọn một
xử lý phù hợp, xử lý tương ứng	nêu đích danh hành vi
dữ liệu lớn, nhiều người dùng	con số + đơn vị

W3 — Mọi con số phải có đơn vị và nguồn

"Tối đa 40" ⇒ 40 ký tự hay 40 byte? Tiếng Hàn/tiếng Việt có dấu khác nhau ở chỗ này. Ghi 40 ký tự (UTF-8, tính theo code point) và nguồn: ai chốt, ngày nào.

W4 — Luồng lỗi là bắt buộc, không phải phần thêm

Mỗi hành động phải có tối thiểu: luồng thành công · luồng validation fail · luồng hệ thống lỗi (timeout/5xx) · luồng không đủ quyền. Thiếu luồng lỗi ⇒ dev tự bịa ⇒ mỗi màn hình một kiểu.

W5 — Text hiển thị viết nguyên văn, trong bảng riêng

Nhãn, placeholder, hint, thông điệp lỗi, text màn hình rỗng, nhãn trạng thái — BA sở hữu những chuỗi này. Viết đúng từng ký tự vào bảng, đủ mọi ngôn ngữ hỗ trợ. Không viết "hiển thị thông báo lỗi phù hợp".

W6 — Trạng thái phải có sơ đồ chuyển

Thực thể có trạng thái ⇒ phải có bảng: trạng thái nguồn | sự kiện | điều kiện | trạng thái đích | ai được làm. Kèm câu trả lời cho: trạng thái khởi tạo là gì, trạng thái nào là cuối, từ trạng thái cuối có quay lại được không.

W7 — Phân biệt "ẩn" và "khoá"

Ba trạng thái khác nhau, đừng gộp: không hiển thị · hiển thị nhưng disable · hiển thị và read-only. Mỗi field/nút trong bảng component phải chỉ rõ cái nào, theo điều kiện gì.

W8 — Cấm quyết định thay PO trong tài liệu

Gặp chỗ chưa rõ, viết:

> **OQ-012** — Đơn hàng đã huỷ có được tính vào doanh thu tháng không?
> **Hỏi:** PO (chị Lan) · **Từ:** 2026-08-28 · **Chặn:** AC-US059-04, BR-021
> **Phương án BA đề xuất:** Không tính, vì … *(đề xuất, chưa phải quyết định)*

Không được im lặng chọn một phương án rồi viết như thể đã chốt. Đó là nguồn gốc của phần lớn CR ở giai đoạn UAT.

W9 — Truy vết trong chính câu văn

Mỗi AC ghi kèm US nó phục vụ; mỗi BR ghi kèm RQ nó hiện thực hoá; mỗi field ghi kèm BR quy định nó. Truy vết nằm rải trong tài liệu, RTM chỉ tổng hợp lại — không phải ngược lại.

W10 — Viết cho ba người đọc cùng lúc

Người đọc	Họ tìm gì	Đáp ứng bằng
PO	Có đúng cái tôi cần không	Mục tóm tắt nghiệp vụ đầu tài liệu, ngôn ngữ nghiệp vụ
Dev	Tôi code gì	Bảng field, bảng component, mã lỗi, API
QA	Tôi test gì	AC Given/When/Then, bảng dữ liệu biên

Một tài liệu, ba mục tiêu. Đừng viết SRS chỉ cho dev đọc.

W11 — Ảnh không thay lời

Wireframe (WF) và prototype minh hoạ bố cục. Hành vi luôn nằm ở bảng component và AC. Khi hình và bảng mâu thuẫn: bảng thắng về "có tồn tại không" và "hành xử thế nào", hình thắng về "nằm ở đâu, to bằng nào". Ghi rõ quy tắc này trong mỗi tài liệu có hình, và ghi từng mâu thuẫn vào WF §5 kèm người quyết — mâu thuẫn không ghi là mâu thuẫn dev sẽ tự xử. Hệ quả: prototype có thành phần mà SRS không có ⇒ không tự thêm vào SRS; đó là scope creep bằng hình ảnh, PO quyết.

W12 — Ghi cả cái tài liệu KHÔNG nói

Cuối mỗi tài liệu, mục "Ngoài phạm vi": những thứ người đọc có thể tưởng là có nhưng không có. Ví dụ: "Không xử lý đơn hàng đa tiền tệ trong phiên bản này". Nó ngăn dev làm thừa và ngăn PO tưởng đã có.

W13 — Sơ đồ vẽ bằng mermaid, và luôn có bảng đi kèm

Hai vế, cả hai bắt buộc.

Vế 1 — mermaid, không ASCII art. ASCII vỡ khi dán sang Confluence/PowerPoint, git diff ra một khối rác, và ký hiệu tự chế khiến khách quen UML/BPMN đọc lệch. Loại sơ đồ nào dùng cú pháp nào, quy ước ID/nhãn/hình dạng: diagram-rules.md.

Vế 2 — sơ đồ để nhìn, bảng để truy vết và test. Sơ đồ không diễn đạt được điều kiện chính xác, ai được làm, mã lỗi nào, quy tắc nào chi phối. Sơ đồ đứng một mình là bức tranh đẹp mà QA không viết được test case từ đó.

Sơ đồ	Bảng bắt buộc đi kèm
Quy trình	Bảng bước: ai · input · output · công cụ · thời gian
Vòng đời trạng thái	Bảng chuyển + bảng chuyển bị cấm (sơ đồ không vẽ được cạnh cấm)
Use case	Bảng US: id · vai trò · RQ · MoSCoW
ERD	Bảng thực thể: trường · kiểu · khoá · ràng buộc
Sequence	Bảng bước: mã lỗi mỗi nhánh · timeout · hành vi khi thất bại

Sơ đồ mâu thuẫn bảng ⇒ bảng thắng (hệ quả của W11).

Checklist tự chấm trước khi nộp bất kỳ tài liệu nào

[ ] W1  Không có câu chứa 2 yêu cầu trở lên
[ ] W2  grep từ mơ hồ trả về rỗng
[ ] W3  Mọi con số có đơn vị + nguồn
[ ] W4  Mọi hành động có đủ 4 luồng
[ ] W5  Có bảng text hiển thị nguyên văn
[ ] W6  Thực thể có trạng thái đều có bảng chuyển trạng thái
[ ] W7  Mọi field/nút có điều kiện ẩn/khoá/read-only rõ ràng
[ ] W8  Mọi chỗ chưa rõ là OQ, không phải quyết định ngầm
[ ] W9  Mọi AC/BR/field có tham chiếu ngược
[ ] W10 Có tóm tắt nghiệp vụ cho PO ở đầu
[ ] W11 Có câu quy định ảnh vs bảng; (screen) mọi lệch prototype ↔ SRS nằm ở WF §5
[ ] W12 Có mục "Ngoài phạm vi"
[ ] W13 Sơ đồ dùng mermaid (không ASCII), và mỗi sơ đồ có bảng đi kèm

Quét W13: grep -n '```mermaid' <file> phải khớp số sơ đồ; grep -nE '^\s*[┌└├│─▼]' <file> phải rỗng.

In checklist này dạng bảng ☐/✅ ở cuối mỗi lần chạy skill. Mục chưa đạt ⇒ nói rõ thiếu gì, không được đánh ✅ cho có.

7.4 KiB Raw Blame History