Cách đọc chính tả báo cáo lỗi để người khác có thể tái hiện

"Lại lỗi rồi" là một lời báo cáo trung thực. Nhưng đó cũng là một lỗi khó sửa. Đến lúc bạn mở công cụ theo dõi lỗi, màn hình, nút bấm và kết quả cụ thể đã lẫn vào nhau trong trí nhớ. Đọc báo cáo lỗi bằng giọng nói giúp giữ lại những chi tiết ấy khi chúng còn mới, nhưng chỉ khi bạn sắp xếp lời kể trước khi bắt đầu.

Đây là một quy trình ngắn để biến sự cố bạn quan sát được thành báo cáo mà người khác có thể tái hiện. Nó hữu ích dù bạn đang thử nghiệm dự án cá nhân, báo lỗi ở nơi làm việc hay hỗ trợ duy trì một công cụ mã nguồn mở. Bạn vẫn cần gõ chính xác các lệnh và kiểm tra báo cáo cuối cùng. Giọng nói dùng để kể lại điều đã xảy ra, không phải để bịa ra bằng chứng.

Bắt đầu từ sự cố, không phải chẩn đoán

Báo cáo lỗi dễ đi chệch hướng khi tiêu đề nêu một giả thuyết: "Bộ nhớ đệm cơ sở dữ liệu bị hỏng." Có thể bạn đúng, nhưng người điều tra cần biết điều bạn quan sát được trước tiên. Tiêu đề tốt hơn nêu hành động và kết quả: "Lưu bản nháp làm mất ngôn ngữ đã chọn trong Cài đặt." Điều này có thể kiểm chứng mà không cần chấp nhận giả thuyết của bạn về nguyên nhân.

Quy tắc đó cũng hữu ích khi bạn đọc chính tả. Nói một câu về việc bạn định hoàn thành, rồi một câu về điều phần mềm đã làm thay vì kết quả mong muốn. Đừng mở đầu bằng câu chuyện dài về cả tuần của bạn hay phỏng đoán phân hệ nào bị lỗi. Nếu lỗi xảy ra không thường xuyên, hãy nói rõ. Nếu lần nào cũng xảy ra trên máy của bạn, hãy nói vậy, nhưng đừng khẳng định nó xảy ra với tất cả mọi người.

Tài liệu hướng dẫn tạo vấn đề của GitHub mô tả cách nhập tiêu đề và nội dung rõ ràng, đồng thời lưu ý rằng kho mã có thể cung cấp mẫu báo cáo. Hãy dùng mẫu đó nếu có. Cấu trúc đọc chính tả dưới đây giúp bạn thu thập sự thật trước khi điền vào các trường; nó không phải lý do để bỏ qua hướng dẫn riêng của dự án.

Ghi chú giọng nói gồm năm trường

Mở một bản nháp riêng tư còn trống thay vì gửi thẳng lên công cụ theo dõi lỗi công khai. Đặt con trỏ vào trình soạn thảo và đọc năm trường ngắn. Xuống dòng giữa các trường. Bản nháp đầu tiên nên giống lời kể của nhân chứng, không phải ghi chú phát hành được trau chuốt:

1. Bối cảnh: Bạn đang cố làm gì? Nêu trang, tính năng hoặc thao tác.
2. Các bước: Những thao tác nào gây ra lỗi? Đánh số theo thứ tự.
3. Mong đợi: Bạn kỳ vọng hợp lý kết quả nào?
4. Thực tế: Điều gì xuất hiện trên màn hình? Chỉ trích dẫn thông báo lỗi ngắn sau khi kiểm tra.
5. Phạm vi: Lỗi xảy ra khi nào, trong môi trường nào, và bạn có thể tái hiện không?

Đây là mẫu để sao chép và dán. Thay từng phần trong ngoặc vuông bằng chi tiết đã quan sát. Nếu chưa biết một trường, hãy viết "chưa kiểm tra" thay vì điền câu trả lời nghe có vẻ hợp lý.

Tiêu đề: [hành động] gây ra [kết quả quan sát được]
Bối cảnh: Tôi đang cố [mục tiêu] trong [tính năng/trang].
Các bước tái hiện:
1. [trạng thái ban đầu chính xác]
2. [thao tác đầu tiên]
3. [thao tác tiếp theo]
Mong đợi: [điều lẽ ra phải xảy ra]
Thực tế: [điều đã xảy ra, gồm nội dung lỗi đã kiểm tra]
Tần suất: [một lần / thỉnh thoảng / mỗi lần thử trên thiết bị này]
Môi trường: [phiên bản ứng dụng, hệ điều hành, trình duyệt nếu liên quan]
Bằng chứng: [ảnh chụp an toàn hoặc nhật ký đã xóa dữ liệu nhạy cảm, nếu hữu ích]

Đừng đọc to dấu ngoặc vuông rồi mong chúng tự biến thành cấu trúc có định dạng. Hãy đặt các tiêu đề trong trình soạn thảo trước, rồi đọc vào từng trường. Nếu dùng bàn phím giọng nói trên máy tính như Talkpad cho macOS hoặc Windows, hãy đặt con trỏ trong bản nháp riêng tư và đọc từng trường một. Như vậy bạn dễ dừng lại, xem xét và sửa từng phần trước khi đăng.

Tái hiện một lần, rồi thuật lại từng cú nhấp

Trí nhớ biến một chuỗi thao tác thành bản tóm tắt. "Tôi đổi một cài đặt rồi trang bị lỗi" có thể bỏ sót lần tải lại, lần chuyển tài khoản hoặc biểu mẫu chưa lưu. Hãy lặp lại chuỗi thao tác nếu an toàn, với bản nháp mở bên cạnh ứng dụng gặp lỗi. Dừng sau mỗi thao tác và ghi lại điều bạn đã làm. Đừng liên tục kích hoạt lỗi làm xóa dữ liệu hoặc mất tiền chỉ để diễn đạt hay hơn.

Giữ các bước cụ thể: "Mở Cài đặt, chọn tiếng Tây Ban Nha, nhấp Lưu, mở lại Cài đặt." Tránh kiểu "vào phần tùy chọn như thường lệ rồi làm thao tác đó." Nếu ứng dụng có nhiều nút Lưu, hãy nêu rõ bảng điều khiển. Nếu lỗi chỉ xuất hiện sau khi tải lại, hãy ghi cả bước tải lại. Đồng nghiệp chưa từng thấy màn hình của bạn cũng phải làm theo được mà không cần nhắn hỏi bạn về cú nhấp bị thiếu.

Bạn có thể đọc phần tường thuật, nhưng hãy dùng bàn phím cho những chuỗi dễ sai. Công cụ nhận dạng có thể biến tên gói thành từ thông dụng, đổi chữ hoa chữ thường trong cờ lệnh hoặc làm mất dấu trừ. Hãy dán bản truy vết ngăn xếp hoặc lỗi đã kiểm tra từ ứng dụng thay vì đọc nó lên. Phiên bản cụ thể như 1.4.12 cũng vậy. Xem hướng dẫn về tên và thuật ngữ kỹ thuật của chúng tôi để biết cách xử lý những từ ít rủi ro hơn nhưng vẫn cần kiểm tra kỹ.

Tách biệt kết quả mong đợi và thực tế

Đây là chỗ báo cáo trở nên hữu ích. "Biểu mẫu bị lỗi" gần như không cho người điều tra biết gì. "Sau khi tôi nhấp Lưu, thông báo xác nhận xuất hiện, nhưng ngôn ngữ trở lại tiếng Anh khi tôi mở lại Cài đặt" mô tả một sự khác biệt có thể quan sát. Kết quả mong đợi cũng có thể đơn giản: "Khi tôi mở lại Cài đặt, ngôn ngữ đã lưu vẫn phải là tiếng Tây Ban Nha."

Đừng lén đưa cách sửa đề xuất vào trường kết quả mong đợi. "Ứng dụng nên dùng bộ nhớ đệm khác" là gợi ý triển khai, không phải kỳ vọng mà người dùng nhìn thấy được. Đặt mọi giả thuyết vào ghi chú được đánh dấu rõ ở cuối và giữ nguyên mức độ chưa chắc chắn. Đồng nghiệp của bạn có thể phát hiện nguyên nhân là phản hồi API, ứng dụng khách dùng dữ liệu cũ hoặc một điều hoàn toàn khác.

Khi nhận dạng giọng nói hiểu sai từ phủ định, báo cáo có thể bị đảo ngược ý nghĩa. So sánh "hộp thoại không đóng" với "hộp thoại đã đóng." Hãy đọc lại những câu đó trên màn hình trước khi gửi. Phương pháp hiệu đính ưu tiên rủi ro của chúng tôi đặt từ phủ định, con số và tên riêng lên trước các chỉnh sửa văn phong vì lý do này.

Thêm thông tin môi trường mà không biến báo cáo thành hồ sơ điều tra

Thông tin môi trường tối thiểu nhưng hữu ích thường gồm phiên bản ứng dụng, hệ điều hành, trình duyệt nếu lỗi xảy ra trên trình duyệt, và mọi thiết lập tính năng cần thiết để tái hiện. Chỉ ghi rằng bạn có thể tái hiện trong phiên làm việc mới hoặc trên thiết bị khác nếu thực sự đã thử. Dấu thời gian hoặc tình trạng mạng có ý nghĩa khi nó làm thay đổi kết quả; nếu không, nó chỉ gây nhiễu.

Kiểm tra ảnh chụp màn hình trước khi đính kèm. Tên người dùng, địa chỉ email, mã truy cập, hồ sơ khách hàng và bản xem trước cuộc trò chuyện có thể nằm khuất ở các góc. Hãy cắt ảnh lấy vùng liên quan hoặc làm mờ chi tiết nhạy cảm bằng trình chỉnh sửa đáng tin cậy. Nhật ký cũng cần được kiểm tra như vậy. Nếu công cụ theo dõi lỗi là công khai, hãy coi tệp đính kèm cũng sẽ công khai. Với các câu hỏi về chính sách nơi làm việc, hãy xem danh sách kiểm tra quyền riêng tư khi nhập liệu bằng giọng nói của chúng tôi trước khi đọc nội dung mật vào bất kỳ công cụ nào.

Talkpad có thể đưa bản nháp bạn đọc vào ứng dụng tại vị trí con trỏ, nhưng không xác minh ảnh chụp màn hình có an toàn hay bản truy vết ngăn xếp có chính xác không. Bạn phải tự kiểm tra những điều đó. Nếu chính sách công ty hạn chế xử lý giọng nói đối với dữ liệu sự cố, hãy tuân thủ chính sách và tự gõ những phần nhạy cảm.

Chỉnh sửa hai lượt trước khi gửi

Lượt một tập trung vào khả năng tái hiện. Bắt đầu từ trạng thái đã ghi và làm đúng từng bước. Lỗi có xuất hiện không? Kết quả mong đợi và thực tế có khác nhau và dễ hiểu không? Bạn có bỏ sót bước đăng nhập hay một cài đặt làm thay đổi kết quả không? Nếu không thể tái hiện lần nữa, hãy sửa trường tần suất cho đúng thay vì che giấu sự không chắc chắn.

Lượt hai tập trung vào rủi ro. Đối chiếu chuỗi phiên bản và thông báo lỗi với nguồn gốc của chúng. Xóa thông tin bí mật khỏi nội dung và tệp đính kèm. Thay suy đoán bằng sự thật có thể quan sát hoặc ghi rõ đó là giả thuyết. Rút ngắn phần mở đầu nếu nó làm chậm việc đến các bước tái hiện. Bạn có thể dùng bộ công cụ chỉnh sửa bản nháp đọc chính tả khi bản nháp đầu tiên là một đoạn lời nói liền mạch thay vì các trường rõ ràng.

Báo cáo hữu ích không nhất thiết phải dài. Có lỗi chỉ cần ba bước và hai câu; có lỗi cần một ví dụ được kiểm soát. Đừng thêm chữ cho đủ dài. Mục tiêu là để người khác tái hiện được hành vi và hiểu vì sao bạn kỳ vọng kết quả khác. Nếu chưa giải thích được trạng thái ban đầu, hãy tìm hiểu thêm một chút trước khi đăng.

Câu hỏi thường gặp

Tôi có thể dùng đọc chính tả để viết báo cáo lỗi không?

Có. Hãy đọc bối cảnh, các bước tái hiện và hành vi mong đợi so với thực tế vào một bản nháp riêng tư. Gõ và xác minh chính xác các lệnh, thông báo lỗi, URL và số phiên bản trước khi chia sẻ.

Báo cáo lỗi nên gồm những gì?

Hãy gồm tiêu đề rõ ràng, bối cảnh ban đầu, các bước theo thứ tự, kết quả mong đợi, kết quả thực tế, môi trường liên quan và bằng chứng an toàn nếu cần. Làm theo mẫu báo cáo của kho mã nếu có.

Làm sao báo cáo lỗi mà tôi không thể tái hiện?

Nói rõ lỗi xảy ra một lần hay không thường xuyên, ghi lại những gì bạn quan sát và thông tin môi trường bạn biết, đồng thời nêu những lần thử không tái hiện được. Đừng điền các bước chưa biết bằng phỏng đoán.

Tôi có nên đính kèm nhật ký vào báo cáo công khai không?

Chỉ sau khi kiểm tra nhật ký để tìm thông tin bí mật và dữ liệu cá nhân. Xóa hoặc che dữ liệu nhạy cảm và chia sẻ đoạn trích ngắn nhất giúp giải thích sự cố. Tuân thủ quy định về sự cố và quyền riêng tư của nhóm bạn.

Tải Talkpad miễn phí – 2.500 từ/tuần với gói miễn phí.