Chuẩn và quy ước viết tài liệu
Trang này quy định tài liệu dự án ADang viết theo chuẩn nào và viết như thế nào. Ai viết tài liệu cho dự án đều phải đọc trang này trước.
Bốn chuẩn được áp dụng
| Chuẩn | Dùng cho phần nào |
|---|---|
| ISO/IEC/IEEE 29148:2018 | Tài liệu yêu cầu (nhóm 3) |
| ISO 24495-1:2023 — Ngôn ngữ đơn giản | Cách hành văn của toàn bộ tài liệu |
| Diátaxis | Hướng dẫn sử dụng (nhóm 7) |
| arc42 | Tài liệu kiến trúc (nhóm 4) |
ISO/IEC/IEEE 29148:2018 — đặc tả yêu cầu
Đây là chuẩn hiện hành cho tài liệu yêu cầu phần mềm. Nó thay thế IEEE 830-1998 — chuẩn cũ vẫn được nhiều nơi ở Việt Nam dùng theo thói quen, nhưng đã hết hiệu lực từ 2011.
Khác biệt đáng kể: IEEE 830 chỉ mô tả cấu trúc tài liệu SRS, còn 29148 bao trùm cả quy trình — thu thập, phân tích, đặc tả, kiểm chứng yêu cầu. Với ADang, điều này có nghĩa là mỗi yêu cầu phải truy vết được ngược về buổi khảo sát nào, và xuôi tới test case nào.
Mỗi yêu cầu phải thoả 5 tính chất (theo mục 5.2.5 của chuẩn):
| Tính chất | Nghĩa là | Ví dụ sai | Ví dụ đúng |
|---|---|---|---|
| Cần thiết | Bỏ đi thì hệ thống thiếu | "Giao diện nên đẹp" | "Nhân viên xem được danh sách việc của mình" |
| Rõ ràng | Chỉ hiểu được một cách | "Hệ thống phản hồi nhanh" | "Danh sách công việc hiển thị trong vòng 3 giây" |
| Kiểm chứng được | Test được pass/fail | "Dễ sử dụng" | "Cán bộ tạo được công việc mới trong dưới 5 thao tác" |
| Khả thi | Làm được trong nguồn lực hiện có | "Tự động phân việc bằng AI" | "Người giao việc chọn người phụ trách từ danh sách" |
| Truy vết được | Biết từ đâu ra, đi tới đâu | (không có nguồn) | "Từ khảo sát ngày ../.., xem FR-TASK-06" |
Quy ước mã yêu cầu: FR-<MODULE>-<số> cho yêu cầu chức năng, NFR-<nhóm>-<số> cho phi chức năng.
Ví dụ: FR-TASK-06, NFR-PERF-02. Mã đã cấp thì không đổi, không dùng lại kể cả khi yêu cầu bị huỷ — huỷ thì ghi trạng thái "Đã huỷ", giữ nguyên mã.
ISO 24495-1:2023 — ngôn ngữ đơn giản
Chuẩn quốc tế về viết cho người đọc phổ thông, ban hành năm 2023. Đây là chuẩn quan trọng nhất với ADang, vì người đọc tài liệu này là thầy cô và cán bộ, không phải kỹ sư phần mềm.
Chuẩn đặt ra bốn nguyên tắc — người đọc phải:
- Tìm được thứ họ cần
- Hiểu được thứ họ tìm thấy
- Dùng được thứ họ hiểu
- Và nội dung phải phù hợp với họ
Điểm mấu chốt của chuẩn: đo bằng việc người đọc dùng được tài liệu hay không, chứ không đo bằng công thức đếm số từ trong câu.
Quy tắc hành văn bắt buộc
Áp dụng cho mọi trang tài liệu.
Viết tiếng Việt hoàn toàn. Thuật ngữ tiếng Anh chỉ được dùng khi không có từ tiếng Việt tương đương và phải giải thích ngay lần đầu xuất hiện.
| Đừng viết | Hãy viết |
|---|---|
| Assign task cho user | Giao việc cho nhân viên |
| Filter theo status | Lọc theo trạng thái |
| Deadline | Hạn hoàn thành |
| Dashboard | Màn hình tổng quan |
| Login/Logout | Đăng nhập / Đăng xuất |
| Comment | Bình luận, trao đổi |
| Upload file | Đính kèm tệp |
| Export Excel | Xuất ra tệp Excel |
| Reassign | Chuyển giao lại |
| Notification | Thông báo |
| MVP | Bản dùng thử |
| Pilot | Triển khai thử nghiệm |
| UAT | Nghiệm thu cùng người dùng |
| Test case | Tình huống kiểm thử |
| User story | Mô tả theo lời người dùng |
| Pain point | Khó khăn, vướng mắc |
| Rollback | Quay về cách làm cũ |
| Staging / Production | Bản thử / Bản chính thức |
| Module | Nhóm chức năng |
| P0 / P1 | Bắt buộc / Giai đoạn sau |
| Input / Output | Dữ liệu nhập vào / Kết quả trả ra |
Câu ngắn, một ý một câu. Câu dài quá ba dòng thì tách ra.
Chủ động thay vì bị động. Viết "Trưởng phòng giao việc cho nhân viên", không viết "Công việc được giao bởi trưởng phòng".
Xưng hô nhất quán. Tài liệu hướng dẫn sử dụng gọi người đọc là "bạn" hoặc "thầy/cô". Tài liệu kỹ thuật gọi theo vai trò: "trưởng phòng", "nhân viên".
Nói cái gì trước, giải thích sau. Câu đầu tiên của mỗi mục phải trả lời thẳng câu hỏi của mục đó.
Không viết tắt tuỳ tiện. BGH được dùng vì phổ biến trong trường học. CRUD, RBAC, API không được xuất hiện trong tài liệu dành cho người dùng.
Một khái niệm chỉ gọi bằng một tên. Đã gọi "chức năng" thì không chỗ nào gọi "tính năng". Đã gọi "bản dùng thử" thì không xen "bản đầu" hay "MVP". Người đọc không chuyên rất dễ tưởng hai tên khác nhau là hai thứ khác nhau.
| Khái niệm | Tên duy nhất được dùng |
|---|---|
| Đơn vị chức năng | chức năng |
| Nhóm chức năng | nhóm |
| Sản phẩm giai đoạn đầu | bản dùng thử |
| Khoảng thời gian chạy thử | giai đoạn thử nghiệm |
| Màn hình 4 ô đếm | màn hình tổng quan |
| Tài liệu đính kèm | tệp |
Hai lớp tài liệu, hai kiểu người đọc
Đây là quy tắc chống nhầm lẫn quan trọng nhất của dự án.
| Lớp nghiệp vụ | Lớp kỹ thuật | |
|---|---|---|
| Nhóm tài liệu | 1, 2, 3, 5, 6, 7 | 4 (Thiết kế) |
| Người đọc | Thầy cô, cán bộ sở, ban giám hiệu | Lập trình viên |
| Được dùng thuật ngữ kỹ thuật | Không | Có |
| Ví dụ dùng được | "Hệ thống nhắc trước hạn một ngày" | "Cron job quét bảng tasks mỗi 15 phút" |
Một trang tài liệu chỉ thuộc một lớp. Nếu thấy mình đang viết sơ đồ cơ sở dữ liệu trong trang dành cho cán bộ sở, nghĩa là đã đặt sai chỗ.
Diátaxis — cách tổ chức hướng dẫn sử dụng
Diátaxis chia tài liệu người dùng thành bốn loại theo nhu cầu tại thời điểm đọc. Trộn lẫn bốn loại này là nguyên nhân phổ biến nhất khiến tài liệu hướng dẫn trở nên khó dùng.
| Loại | Người đọc đang cần gì | Trong ADang |
|---|---|---|
| Bài học | Học từ đầu, chưa biết gì | "Buổi đầu làm quen với phần mềm" |
| Cách làm | Giải quyết một việc cụ thể | "Cách giao việc cho nhân viên" |
| Tra cứu | Tra một thông tin chính xác | Bảng ý nghĩa các trạng thái công việc |
| Giải thích | Hiểu vì sao lại thế | "Vì sao nhân viên không tự đóng được việc" |
Quy tắc: không trộn hai loại trong một trang. Đang viết "Cách giao việc" thì không giải thích triết lý thiết kế — để dành cho trang giải thích và đặt liên kết sang.
Yêu cầu về ảnh minh hoạ
Người đọc không chuyên phụ thuộc vào ảnh nhiều hơn chữ.
- Mỗi bước thao tác trong hướng dẫn sử dụng phải có một ảnh chụp màn hình
- Ảnh phải chụp giao diện tiếng Việt, không chụp bản tiếng Anh
- Khoanh đỏ đúng chỗ cần bấm
- Dữ liệu trong ảnh phải là ví dụ thật của trường, không để "Lorem ipsum" hay "Task-1234"
- Mỗi ảnh có chú thích bên dưới nói ảnh đó là màn hình gì
Quy trình một trang tài liệu đi qua
Viết bản nháp
└─ Tự kiểm theo bảng kiểm bên dưới
└─ Người khác đọc lại (không phải người viết)
└─ Đưa cho một thầy cô không rành máy tính đọc thử
└─ Sửa theo phản hồi → Đăng
Bước áp chót là bắt buộc với nhóm 7 (Hướng dẫn sử dụng). Nếu người đọc thử phải hỏi lại, tài liệu chưa đạt.
Bảng kiểm trước khi đăng
- Không còn thuật ngữ tiếng Anh chưa giải thích
- Không có câu nào dài quá ba dòng
- Mỗi mục trả lời thẳng câu hỏi ở tiêu đề mục, ngay câu đầu
- Yêu cầu nào cũng kiểm chứng được pass/fail (với nhóm 3)
- Ảnh chụp là giao diện tiếng Việt, có khoanh vùng và chú thích
- Trang không trộn lớp nghiệp vụ với lớp kỹ thuật
- Đã có người thứ hai đọc lại
Một điểm cần xác nhận về mặt pháp lý
Nếu dự án này dùng vốn ngân sách nhà nước, hồ sơ phải tuân theo Nghị định 73/2019/NĐ-CP về quản lý đầu tư ứng dụng công nghệ thông tin, đã được sửa đổi bởi Nghị định 82/2024/NĐ-CP. Quy định này bắt buộc một danh mục hồ sơ riêng — thiết kế sơ bộ, thiết kế thi công, dự toán, hồ sơ hoàn thành — khác với bộ tài liệu kỹ thuật đang dựng ở đây.
Bộ tài liệu hiện tại xây theo chuẩn kỹ thuật quốc tế, chưa theo danh mục hồ sơ của hai nghị định trên. Cần xác nhận nguồn vốn của dự án trước khi hoàn thiện. Nếu là vốn ngân sách, phải bổ sung hồ sơ theo quy định, không thay thế được bằng tài liệu kỹ thuật.
Nguồn tham khảo
- ISO/IEC/IEEE 29148:2018 — Kỹ thuật yêu cầu
- ISO 24495-1:2023 — Ngôn ngữ đơn giản
- Diátaxis — Khung tổ chức tài liệu
- arc42 — Mẫu tài liệu kiến trúc