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)

Khi nào nên dừng lại?

  • Khi nội dung đã có thể giúp người đọc tự hiểu và hành động
  • Khi bạn bắt đầu lặp lại những thứ đã có trong file khác
  • Khi tài liệu dài quá → mất trọng tâm, người đọc bỏ qua phần quan trọng

Mẹo kiểm tra tài liệu vừa đủ:

  1. Dev đọc xong → tự code được
  2. QA đọc xong → tự viết test case
  3. Khách đọc xong → có thể confirm hoặc phản hồi đúng nội dung
  4. Bạn không cần kèm lời giải thích trong cuộc họp

Nếu đạt cả 4 điều này → bạn có thể tạm dừng

Mình từng gặp gì?

  • Có lần viết 18 trang mô tả 1 module nhỏ → dev bỏ qua gần hết
  • Sau rút gọn thành 3 trang + 1 sơ đồ → dev hiểu và code đúng
  • Từ đó, mình luôn hỏi: “Cái này có cần thiết không?” trước khi viết thêm

Kết luận

Viết tài liệu là kỹ năng truyền đạt có mục tiêu – không phải ghi chép mọi thứ bạn biết
Là BrSE, bạn cần biết điểm dừng – để team đọc, hiểu, làm đúng mà không bị quá tải

👉 Bài tiếp theo: “Phân tích dữ liệu đầu vào – điều BrSE hay bỏ sót”