Một sự thật đau đầu:
“Viết spec dài mấy chục trang mà team vẫn hiểu sai.”
Vấn đề không nằm ở số trang – mà ở format và mức độ dễ đọc.
Là BrSE, bạn phải viết sao cho người đọc có thể:
- Scan nhanh → hiểu logic
- Biết phần nào mình cần làm/test/xác nhận
- Không cần hỏi lại những điều cơ bản
Format nào thường gặp? Ưu nhược điểm?
1. Spec dạng đoạn văn (doc)
- ✅ Dễ viết nhanh, copy/paste từ mail
- ❌ Dễ lan man, khó scan
- ❌ Không thể hiện rõ logic rẽ nhánh hoặc các trường hợp đặc biệt
2. Spec dạng bảng (table)
- ✅ Rõ ràng từng điều kiện – xử lý – kết quả
- ✅ Dễ đối chiếu giữa team
- ❌ Với logic quá phức tạp → bảng bị dài, khó đọc theo chiều ngang
3. Spec kết hợp bảng + flowchart
- ✅ Hiệu quả cao nhất
- ✅ Dùng bảng cho từng step, flowchart cho overview
- ❌ Tốn thời gian hơn lúc đầu, cần công cụ hỗ trợ (draw.io, miro…)
Format mình thường dùng
Bắt đầu bằng bảng xử lý chính:
Step Điều kiện Xử lý Kết quả 1 Khi nhấn nút Lưu Validate input Nếu lỗi → hiển thị message 2 Nếu input OK Gọi API save Trả về status + hiển thị “OK” Kèm flowchart nếu có rẽ nhánh hoặc nhiều role xử lý
Nếu liên quan UI:
- Gắn screenshot UI + chú thích vùng nào → xử lý nào
- Mô tả logic validation, tooltip, hoặc format đầu vào nếu có
Lưu ý cho từng đối tượng đọc
- Dev: cần logic xử lý, dữ liệu input/output, API liên quan
- QA: cần điều kiện test từng trường hợp, error case
- Khách: cần mô tả đơn giản, dễ xác nhận (tránh từ kỹ thuật)
📌 Vậy nên: cùng 1 spec → bạn nên chia section theo đối tượng đọc nếu cần
Kết luận
Không có 1 format chuẩn cho mọi loại tài liệu – nhưng có những nguyên tắc chung:
- Trình bày rõ ràng theo block, không để người đọc phải đoán
- Dùng bảng và sơ đồ nếu logic có nhánh
- Ghi rõ input/output – xử lý – hiển thị
👉 Bài tiếp theo: “Viết mô tả nghiệp vụ cho người không kỹ thuật – làm sao cho dễ hiểu?”