Hướng dẫn đầy đủ về báo cáo lỗi trực quan

Mọi nhà phát triển đều đã nhận được báo cáo lỗi đó. "Trang trông lạ." "Có lỗi." "Nó không hoạt động." Ba phút trao đổi qua lại sau đó: "Trang nào? Lỗi gì? Bạn đã nhấp vào đâu?" Lỗi có thể mất hai phút để sửa, nhưng để hiểu nó thì mất mười phút.

Một ảnh chụp màn hình có chú thích duy nhất loại bỏ gần như tất cả sự khó khăn đó. Vấn đề hiển thị rõ ràng. Vị trí rõ ràng. Các bước được đánh số. Nhà phát triển mở vấn đề, thấy chính xác lỗi gì và bắt đầu sửa ngay lập tức.

Hướng dẫn này bao gồm mọi thứ bạn cần biết về báo cáo lỗi trực quan: tại sao nó hiệu quả, cách thực hiện tốt, các kỹ thuật chú thích giúp tiết kiệm thời gian nhất và nên sử dụng công cụ nào.

Tại sao ảnh chụp màn hình tốt hơn văn bản trong báo cáo lỗi

Các báo cáo lỗi dựa trên văn bản gặp phải ba vấn đề cơ bản:

Sự mơ hồ. "Nút trên trang cài đặt không hoạt động" có thể có nghĩa là bất kỳ nút nào trong số 15 nút. "Nút gửi trong bảng tùy chọn thông báo" thu hẹp phạm vi, nhưng vẫn yêu cầu nhà phát triển điều hướng đến đó, tìm nút và cố gắng tái tạo. Một ảnh chụp màn hình với mũi tên chỉ vào nút sẽ giải quyết sự mơ hồ ngay lập tức.

Thiếu ngữ cảnh. Người báo cáo lỗi mô tả những gì họ nghĩ là có liên quan, điều này thường không phải là những gì nhà phát triển cần. Một ảnh chụp màn hình ghi lại mọi thứ trong tầm nhìn — thông báo lỗi, URL, trạng thái trình duyệt, các yếu tố UI xung quanh — cho dù người báo cáo có nghĩ đến việc đề cập đến chúng hay không. Nhiều lỗi được chẩn đoán từ một điều gì đó hiển thị trong ảnh chụp màn hình mà người báo cáo chưa bao giờ đề cập.

Khó tái hiện. "Tôi đã nhấp và nhận được lỗi" không giúp nhà phát triển tái hiện vấn đề. Một loạt ảnh chụp màn hình được đánh số hiển thị từng bước — "1. Mở cài đặt, 2. Nhấp xuất, 3. Nhận hộp thoại lỗi này" — biến một báo cáo mơ hồ thành một trường hợp thử nghiệm có thể tái hiện.

Nghiên cứu từ Microsoft và Đại học Zurich cho thấy các báo cáo lỗi có tệp đính kèm trực quan được giải quyết nhanh hơn 13-18% so với các báo cáo chỉ có văn bản. Trong các tổ chức lớn với hàng trăm báo cáo lỗi mỗi tuần, việc tiết kiệm thời gian đó là rất lớn.

Giải phẫu một ảnh chụp màn hình báo cáo lỗi hiệu quả

Không phải tất cả ảnh chụp màn hình đều được tạo ra như nhau. Một ảnh chụp màn hình thô, không chú thích tốt hơn không có gì, nhưng một ảnh chụp màn hình có chú thích tốt hơn ảnh thô. Đây là điều phân biệt các báo cáo lỗi trực quan tốt với những báo cáo tuyệt vời:

1. Chụp đúng khu vực

Sử dụng chụp vùng, không phải chụp toàn màn hình. Mục tiêu là hiển thị đủ ngữ cảnh để xác định vị trí vấn đề, nhưng không quá nhiều đến mức người xem phải tìm kiếm nó. Đối với lỗi UI, hãy chụp thành phần cộng với môi trường xung quanh ngay lập tức. Đối với hộp thoại lỗi, hãy chụp hộp thoại với đủ nền để hiển thị điều gì đã kích hoạt nó.

2. Chỉ ra vấn đề

Sử dụng mũi tên hoặc hình tròn để chỉ rõ chính xác vấn đề nằm ở đâu. Ngay cả khi lỗi có vẻ hiển nhiên với bạn, hãy nhớ rằng nhà phát triển có thể có mười vấn đề khác đang chờ xử lý. Một mũi tên sẽ loại bỏ mọi sự mơ hồ về những gì bạn đang báo cáo.

3. Thêm Ngữ cảnh bằng Chú thích Văn bản

Một nhãn văn bản ngắn có thể ngăn chặn nhiều sự nhầm lẫn. Ví dụ: "Dự kiến: xanh dương. Thực tế: xanh lá" bên cạnh một màu sai. "Cái này phải là 'Export', không phải 'Expprt'" bên cạnh một lỗi chính tả. "Cái này tải sau 8 giây" trên một thành phần chậm. Giữ nhãn ngắn gọn — tối đa một câu.

4. Đánh Số Các Bước Của Bạn

Đối với các lỗi yêu cầu một chuỗi hành động để tái hiện, các chú thích được đánh số là vô giá. Ví dụ: "Bước 1: Nhấp Cài đặt. Bước 2: Bật chế độ tối. Bước 3: Cuộn xuống cuối. Bước 4: Phần tử này biến mất." Mỗi số trên ảnh chụp màn hình tương ứng với một hành động, tạo ra một hướng dẫn tái hiện trực quan.

5. Che Giấu Thông tin Nhạy cảm

Trước khi đính kèm ảnh chụp màn hình vào bất kỳ công cụ theo dõi lỗi nào, hãy kiểm tra dữ liệu nhạy cảm có thể nhìn thấy: địa chỉ email, API keys, tokens, dữ liệu người dùng cá nhân, URL nội bộ hoặc nội dung cơ sở dữ liệu. Sử dụng công cụ làm mờ hoặc pixelate để che giấu bất cứ thứ gì không nên có trong báo cáo lỗi. Điều này đặc biệt quan trọng đối với các ảnh chụp màn hình có thể xuất hiện trong các vấn đề công khai trên GitHub. Hướng dẫn của chúng tôi về bảo mật ảnh chụp màn hình đề cập chi tiết vấn đề này.

Kỹ thuật Chú thích theo Loại Lỗi

Lỗi Bố cục và CSS

Vẽ hình chữ nhật xung quanh các phần tử bị lệch. Sử dụng đường kẻ để hiển thị căn chỉnh dự kiến. Thêm nhãn văn bản với các giá trị cụ thể: "Khoảng cách dự kiến 16px, thực tế 0px." Nếu bạn có thể mở DevTools và chụp các kiểu đã tính toán, hãy đưa nó vào làm ảnh chụp màn hình thứ hai.

Lỗi Chức năng

Đánh số các bước để tái hiện. Chụp trạng thái trước và sau hành động bị lỗi. Nếu có thông báo lỗi, hãy đảm bảo nó hiển thị đầy đủ và được làm nổi bật bằng hình chữ nhật. Bao gồm bảng điều khiển trình duyệt nếu bạn thấy lỗi ở đó — các nhà phát triển sẽ tìm kiếm lỗi JavaScript, lỗi mạng và các vấn đề CORS.

Lỗi Nội dung và Văn bản

Khoanh tròn văn bản không chính xác. Thêm chú thích văn bản với nội dung dự kiến. Đối với lỗi chính tả, một mũi tên chỉ vào từ cụ thể là đủ. Đối với nội dung bị thiếu, hãy vẽ một hình chữ nhật tại vị trí nội dung đáng lẽ phải xuất hiện và gắn nhãn "Thiếu: [mô tả]."

Lỗi Hiệu suất

Lỗi hiệu suất rất khó chụp trực quan. Cách tốt nhất là chụp ảnh màn hình tab Network của trình duyệt hiển thị các yêu cầu chậm, hoặc tab Performance hiển thị các tác vụ dài. Chú thích bằng dấu thời gian: "Yêu cầu này mất 8.2 giây." Đối với các hoạt ảnh giật cục, quay màn hình hữu ích hơn là chụp ảnh màn hình.

Lỗi Đa Trình duyệt

Chụp hai ảnh màn hình: một từ trình duyệt hoạt động bình thường và một từ trình duyệt bị lỗi. Đặt chúng cạnh nhau hoặc xếp chồng lên nhau theo chiều dọc với các nhãn: "Chrome 120 (đúng)" và "Firefox 121 (lỗi)." Sự khác biệt trực quan làm cho vấn đề trở nên rõ ràng ngay lập tức.

Các Thực hành Tốt nhất cho Nhóm

Tiêu chuẩn hóa công cụ chụp ảnh màn hình của bạn. Khi mọi người trong nhóm sử dụng cùng một công cụ, ảnh chụp màn hình sẽ trông nhất quán và mọi người đều biết những tính năng chú thích nào có sẵn. Maxisnap là một lựa chọn tốt cho các nhóm vì các công cụ chú thích của nó bao gồm tất cả các trường hợp sử dụng phổ biến (mũi tên, số, văn bản, làm mờ) và nó đủ nhẹ để không ai phàn nàn về việc sử dụng tài nguyên.

Thiết lập các quy ước chú thích. Mũi tên đỏ cho "đây là lỗi." Mũi tên xanh lá cho "hành vi dự kiến." Hình chữ nhật màu xanh dương cho "ngữ cảnh liên quan." Vòng tròn được đánh số cho các bước tái hiện. Những quy ước này không cần phải được ghi lại chính thức — một cuộc thảo luận nhóm năm phút là đủ. Một khi đã thiết lập, mỗi báo cáo lỗi sẽ nhanh hơn cả khi tạo và đọc.

Bao gồm thông tin môi trường. Hãy tạo thói quen chụp thanh URL, phiên bản trình duyệt hoặc chỉ báo hệ điều hành trong ảnh chụp màn hình của bạn. Ngữ cảnh này thường bị cắt bỏ khỏi các ảnh chụp vùng nhưng có thể tạo ra sự khác biệt giữa việc tái hiện lỗi và mất hàng giờ để thử. Ngoài ra, hãy bao gồm chi tiết môi trường trong văn bản của báo cáo lỗi cùng với ảnh chụp màn hình.

Sử dụng liên kết tải lên, không phải tệp đính kèm. Một liên kết ảnh chụp màn hình trong bình luận Jira tải ngay lập tức. Một tệp đính kèm PNG 5 MB yêu cầu một cú nhấp chuột và tải xuống. Các công cụ như Maxisnap với tính năng tự động tải lên, tự động tạo liên kết có thể chia sẻ, giúp việc dán URL ảnh chụp màn hình vào bất kỳ công cụ theo dõi lỗi, kênh Slack hoặc email nào trở nên dễ dàng. Thiết lập tải lên SFTP chỉ mất năm phút và cung cấp cho bạn một liên kết vĩnh viễn cho mỗi lần chụp.

Đề xuất công cụ

Công cụ báo cáo lỗi trực quan tốt nhất có ba đặc điểm: chụp nhanh bằng phím tắt (hotkey), chú thích ngay lập tức (không cần chuyển sang trình chỉnh sửa riêng biệt) và chia sẻ nhanh chóng (tải lên hoặc clipboard).

• Maxisnap — Tốt nhất cho các nhóm cần công cụ chụp ảnh nhẹ, điều khiển bằng bàn phím với chú thích ngay lập tức và tải lên máy chủ. 11 công cụ chú thích bao gồm các bước được đánh số và làm mờ. Miễn phí cho mục đích sử dụng cá nhân.
• Snagit — Tốt nhất cho các tổ chức muốn các tính năng chú thích cao cấp và sẵn sàng trả $62.99. Các công cụ đánh số bước và di chuyển thông minh rất xuất sắc cho việc tạo tài liệu.
• ShareX — Tốt nhất cho các nhà phát triển muốn khả năng cấu hình tối đa và không ngại sự phức tạp. Miễn phí và mã nguồn mở.
• Loom — Tốt nhất khi ảnh chụp màn hình không đủ và bạn cần một video hướng dẫn nhanh. Sự kết hợp giữa quay màn hình và tường thuật rất mạnh mẽ cho các lỗi phức tạp. (Nếu bạn đang dùng Monosnap, hãy xem So sánh Maxisnap và Monosnap.)

Lợi tức đầu tư (ROI) của ảnh chụp lỗi tốt

Báo cáo lỗi trực quan không chỉ là một thực hành tốt — nó có tác động đáng kể đến tốc độ phát triển. Hãy xem xét phép tính:

• Một báo cáo lỗi chỉ bằng văn bản yêu cầu trung bình 2-3 lần trao đổi làm rõ trước khi công việc bắt đầu: ~15 phút thời gian chờ tích lũy
• Một ảnh chụp màn hình có chú thích loại bỏ những trao đổi đó: tiết kiệm ~15 phút cho mỗi lỗi
• Một nhóm báo cáo 50 lỗi mỗi tuần tiết kiệm ~12.5 giờ thời gian làm rõ hàng tuần
• Trong một năm, đó là hơn 600 giờ thời gian của nhà phát triển được phục hồi

Và phép tính đó chỉ tính đến thời gian dành cho việc làm rõ. Nó không bao gồm chi phí gián đoạn tập trung — mỗi lần trao đổi làm rõ yêu cầu cả người báo cáo và nhà phát triển phải chuyển đổi ngữ cảnh, mỗi lần tốn thêm 10-15 phút thời gian làm việc hiệu quả.

Bắt đầu

Nếu bạn chưa sử dụng ảnh chụp màn hình có chú thích trong báo cáo lỗi của mình, hãy bắt đầu ngay hôm nay. Tải xuống một công cụ chụp ảnh màn hình có hỗ trợ chú thích, dành năm phút để tìm hiểu phím tắt, và thử chú thích báo cáo lỗi tiếp theo của bạn thay vì viết một đoạn mô tả.

Lần đầu tiên một nhà phát triển phản hồi với "Đã sửa, cảm ơn — ảnh chụp màn hình tuyệt vời" thay vì "Bạn có thể làm rõ bạn muốn nói nút nào không?", bạn sẽ không bao giờ quay lại với các báo cáo lỗi chỉ bằng văn bản nữa.