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

🎯 Đây là bài cuối trong series Tài liệu BrSE – Viết thế nào để team hiểu, khách tin.
Cảm ơn bạn đã đọc đến đây!