143 lines
7.0 KiB
Markdown
143 lines
7.0 KiB
Markdown
# 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ị |
|
|
|
|
Quét trước khi nộp: `grep -niE "nhanh|mượt|thân thiện|v\.v|nên |có thể |phù hợp" <file>`
|
|
|
|
## 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:
|
|
|
|
```markdown
|
|
> **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 minh hoạ bố cục. Hành vi luôn nằm ở bảng component và AC. Khi ảnh và bảng mâu
|
|
thuẫn: **bảng thắng về việc "có tồn tại không"**, ả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ó ảnh.
|
|
|
|
## 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`](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
|
|
[ ] 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ó**.
|