Viết Tài Liệu

Vì sao tôi chọn Google Docs cho tài liệu spec? Khi làm BrSE, bạn sẽ thường xuyên phải gửi tài liệu xác nhận cho khách (仕様書, 要件定義書, …). Trước đây tôi dùng Word → gửi file qua email → khách in ra hoặc chỉnh sửa, rồi gửi lại file mới… Mất thời gian và dễ thất lạc. Từ khi chuyển sang Google Docs, tôi thấy: Việc xác nhận tài liệu nhanh và rõ ràng hơn Khách có thể comment trực tiếp Không còn tình trạng “file_final_v3_fix_khách_修正版.docx” 😅 Cách tôi dùng Google Docs để làm spec 1. Tạo folder riêng cho từng dự án Tôi tạo folder dạng: [KHÁCH]_[Tên dự án]_[yyyyMM] → Giúp tôi quản lý dễ, cả khi chuyển máy. ...

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: ...