Bối cảnh Có một issue khách hỏi – liên quan đến luồng xử lý logic A → B → C Mình đã giải thích chi tiết qua mail, thậm chí có ảnh minh họa + flowchart Nhưng khách phản hồi: “Cảm ơn. Nhưng mai chúng ta hãy họp 15 phút để xác nhận lại trực tiếp.” 👉 Mình ban đầu cảm thấy bị coi thường – vì đã viết rất kỹ mà vẫn bị yêu cầu gặp lại ...
Bối cảnh Dự án có những phần mà khách chỉ nói mơ hồ kiểu: “Phần này cần xử lý linh hoạt hơn.” Không có mockup, không có logic cụ thể, không có deadline Sau 3 ngày, khách gửi mail CC toàn bộ quản lý: “Team xử lý quá chậm. Không thấy tiến triển.” 👉 Cảm giác cực kỳ ức chế – vì team đã hỏi lại nhiều lần nhưng không được câu trả lời rõ. ...
Bối cảnh Dự án có một task xử lý khá phức tạp, QA raise bug vì cho là sai logic Dev phản hồi gay gắt: “Không sai. QA không hiểu spec.” QA thì bảo: “Dev fix theo cảm tính, không theo logic ban đầu.” 👉 Mình đứng giữa, mỗi bên đều gọi riêng để “trình bày chính nghĩa” của mình Phản ứng ban đầu của mình (và sai lầm) Mình cố làm dịu không khí bằng cách… im lặng và nói: “Thôi team tự trao đổi thêm nhé.” Kết quả: mỗi bên hiểu rằng mình không đứng về họ, nên đều cảm thấy bị bỏ rơi ➡️ Căng thẳng leo thang, ảnh hưởng deadline sprint ...
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’” ...
Bối cảnh Mình được giao tiếp nhận một hệ thống đang vận hành Người phụ trách trước đã nghỉ việc Không có tài liệu logic, không có sơ đồ hệ thống, không có môi trường test Khách hàng cũng chỉ nắm tổng thể, không rõ chi tiết 👉 Cảm giác lúc đó: như rơi vào hố đen. Không biết bắt đầu từ đâu. Mình đã làm gì trong 3 ngày đầu tiên? 1. Không vội báo cáo – lập kế hoạch điều tra đầu tiên “Trong 3 ngày tới, tôi sẽ rà lại toàn bộ source code, log, và hệ thống để nắm overview.” ...
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 ...
Một thực tế ít ai nói rõ BrSE hay bị rơi vào tình huống: Khách nói: “Làm giống bên A nhé” → nhưng không rõ logic A là gì Dev hỏi: “Nếu data null thì xử lý sao?” → không có câu trả lời 👉 Đó là vì bạn chưa đào sâu bằng câu hỏi. Phân tích bắt đầu từ câu hỏi Không phải tool, không phải biểu mẫu – mà là: ...
Một ví dụ thực tế Hệ thống nhận file CSV import danh sách đơn hàng Logic xử lý ổn, UI đẹp, message đầy đủ Nhưng khi chạy thử file thật → lỗi hàng loạt: Dữ liệu thiếu cột Có ký tự đặc biệt Format ngày không đồng nhất 👉 Tất cả do… BrSE không confirm rõ cấu trúc & đặc điểm dữ liệu đầu vào Dữ liệu đầu vào quan trọng thế nào? Nó quyết định logic xử lý có áp dụng được không Nó ảnh hưởng đến test case, error handling, import/export, mapping Dữ liệu thực tế luôn bẩn hơn tưởng tượng – nếu không kiểm tra trước, hệ thống dễ hỏng khi live Cần làm gì khi phân tích dữ liệu đầu vào? 1. Xác nhận nguồn dữ liệu “File này do ai tạo?” – “Có quy chuẩn không?” – “Có thay đổi theo thời gian không?” ...
Câu hỏi thực tế: “Tài liệu này nên để ở đâu? Gửi mail? Ghi vào Wiki? Hay làm file riêng?” 👉 Không có câu trả lời duy nhất – nhưng có nguyên tắc lựa chọn phù hợp tuỳ tình huống Đặc điểm từng loại 1. Mail – dùng để trao đổi nhanh, ghi log quyết định ✅ Dễ gửi, nhanh, tiện confirm ❌ Dễ bị trôi nếu không có follow-up hoặc search khó ❌ Không phù hợp để lưu trữ dài hạn 📌 Dùng khi: ...
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) ...