Một logic không rõ ràng sẽ dẫn đến gì? Dev hiểu sai → làm sai QA hiểu khác → test lệch Khách đọc không hiểu → yêu cầu lại 👉 Một logic xử lý không rõ ràng là gốc rễ của rất nhiều vòng lặp sai sót Mô tả logic – không cần dài dòng, nhưng phải đủ Cấu trúc cơ bản: Trigger / Điều kiện bắt đầu “Khi user nhấn nút ‘Lưu’” ...
Vấn đề lớn hơn bạn nghĩ: “Chỉ là ghi thiếu một dòng thôi mà” → nhưng dev hiểu sai hoàn toàn → QA test lệch → khách phản hồi ngược Tài liệu là gốc rễ – nếu viết sai/lệch, cả team sẽ lệch theo ❌ 7 lỗi phổ biến khi viết tài liệu (và cách tránh) 1. Dùng từ mơ hồ ❌ “Hệ thống xử lý dữ liệu phù hợp” → phù hợp là sao? ✅ “Hệ thống sẽ validate theo định dạng yyyy/mm/dd và reject nếu sai” 2. Thiếu xử lý trường hợp ngoại lệ (exception) Ghi luồng chính nhưng không ghi: nếu user không chọn gì thì sao? nếu API trả lỗi thì sao? 3. Mô tả không rõ thứ tự các bước ❌ Viết thành đoạn dài → không biết trước/sau ✅ Dùng bullet hoặc đánh số 1, 2, 3 4. Thiếu thông tin cho các vai trò khác nhau Viết theo dev → QA không hiểu gì Viết cho khách → dev không đủ logic 👉 Hãy chia block: dành cho dev, QA, khách 5. Viết dài dòng nhưng không rõ trọng tâm Dài không có nghĩa là rõ Thay vì viết 5 dòng lan man → tóm 1 dòng gọn nhưng đủ logic 6. Không định nghĩa thuật ngữ/nghiệp vụ đặc biệt Từ nội bộ, từ viết tắt, nghiệp vụ tiếng Nhật → cần glossary hoặc chú thích 7. Không thống nhất định dạng Font, cách viết heading, numbering khác nhau → người đọc mất tập trung, khó scan Cách tránh các lỗi này Dùng checklist gửi trước đó Có người review chéo (ngay cả không phải dev/QA) Đọc lại với tư duy: “Nếu tôi là người không viết, tôi hiểu không?” Kết luận BrSE giỏi không cần viết tài liệu thật đẹp – nhưng bắt buộc phải rõ Tránh được 7 lỗi này → tài liệu của bạn sẽ giúp team hiểu nhanh, làm đúng và tiết kiệm thời gian phản hồi ...
Sự thật: Viết tài liệu không phải để ‘đẹp’ mà để ‘hiểu’ Viết quá ít → người khác không hiểu Viết quá nhiều → không ai đọc 👉 Tài liệu hiệu quả là tài liệu có người đọc và hiểu đúng để hành động Khi nào cần viết chi tiết? Logic phức tạp → cần flow rõ ràng Có nhiều điều kiện rẽ nhánh Người đọc không cùng văn hoá/ngôn ngữ (offshore, khách Nhật) Bạn không phải người trực tiếp giải thích lại sau này 📌 Nguyên tắc: “càng ít gặp – càng cần viết rõ” (ví dụ: lỗi hiếm gặp, case đặc biệt) ...
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: ...