Vấn đề thường gặp:

“Khách đọc spec mà vẫn hỏi lại: ‘Rốt cuộc hệ thống sẽ làm gì?’”

Lý do?

  • Tài liệu quá thiên về kỹ thuật
  • Viết theo kiểu code, không theo kiểu người dùng

📌 Nếu mô tả nghiệp vụ mà dev hiểu – nhưng khách không hiểu → bạn chưa hoàn thành vai trò BrSE

Mục tiêu của phần mô tả nghiệp vụ là gì?

  • Giúp người không kỹ thuật hình dung được hệ thống làm gì
  • Hiểu luồng thao tác từ góc nhìn người dùng
  • Có thể xác nhận được logic xử lý ở mức khái quát

Cách viết dễ hiểu hơn:

1. Bắt đầu từ hành vi người dùng, không phải xử lý kỹ thuật

❌ “Khi submit, hệ thống gọi API /v1/post-item và update bảng ITEM.”
✅ “Khi người dùng nhấn Lưu, dữ liệu được ghi nhận và hiển thị thông báo thành công.”

2. Tránh từ chuyên môn nếu không cần thiết

  • Dùng “lưu dữ liệu”, “hiển thị cảnh báo” thay vì “trigger DB”, “show toast message”

3. Sử dụng ví dụ cụ thể

“Ví dụ: khi người dùng nhập ngày sinh là 2050/01/01, hệ thống sẽ hiển thị lỗi: ‘Ngày không hợp lệ’”

4. Tách logic kỹ thuật ra phần sau

  • Dùng layout:
    • Mô tả tổng quan nghiệp vụ (cho khách, QA)
    • Chi tiết xử lý (cho dev)

Template đơn giản gợi ý

Tiêu đề chức năng: Nhập thông tin đơn hàng mới
Mục tiêu: Cho phép người dùng đăng ký đơn hàng
Đối tượng sử dụng: Nhân viên bán hàng
Luồng thao tác:

  1. Nhập thông tin sản phẩm và khách hàng
  2. Nhấn nút “Tạo đơn”
  3. Hệ thống hiển thị màn hình xác nhận

Trường hợp đặc biệt: Nếu khách hàng là thành viên VIP → hiển thị thông báo ưu đãi

Kết luận

Viết cho người không kỹ thuật là một kỹ năng truyền đạt bằng sự thấu hiểu.
Hãy luôn đọc lại tài liệu từ góc nhìn của người ngoài – và đơn giản hoá bằng ví dụ, từ dễ hiểu, và trình bày thân thiện.

👉 Bài tiếp theo: “So sánh giữa mail, wiki, doc – dùng cái nào khi nào?”