Cara Mendikte Laporan Bug yang Dapat Direproduksi Orang Lain

"Rusak lagi" adalah laporan yang jujur. Namun, laporan seperti itu juga sulit ditindaklanjuti. Saat Anda membuka pelacak isu, detail layar, tombol, dan hasilnya sudah mulai kabur. Mendikte laporan bug dapat mempertahankan detail itu selagi masih segar, tetapi hanya jika Anda menyusun alurnya sebelum mulai berbicara.

Ini adalah alur kerja singkat untuk mengubah kegagalan yang Anda amati menjadi laporan yang dapat direproduksi orang lain. Cara ini berlaku saat Anda menguji proyek sampingan, melaporkan masalah di tempat kerja, atau membantu memelihara perangkat sumber terbuka. Anda tetap perlu mengetik perintah secara persis dan memeriksa laporan akhir. Suara berguna untuk menceritakan apa yang terjadi, bukan untuk mengarang bukti.

Mulailah dari kegagalannya, bukan diagnosisnya

Laporan bug melenceng ketika judulnya langsung menyatakan dugaan: "Cache basis datanya rusak." Anda mungkin benar, tetapi orang yang menyelidikinya perlu mengetahui pengamatannya terlebih dahulu. Judul yang lebih baik menyebut tindakan dan hasilnya: "Menyimpan draf menghapus bahasa yang dipilih di Pengaturan." Hal itu dapat diuji tanpa harus menerima dugaan Anda tentang penyebabnya.

Aturan yang sama membantu saat Anda mendikte. Ucapkan satu kalimat tentang tugas yang ingin Anda selesaikan, lalu satu kalimat tentang apa yang justru dilakukan perangkat lunak. Jangan mulai dengan cerita panjang tentang minggu Anda atau tebakan mengenai subsistem yang gagal. Jika masalahnya terjadi sesekali, katakan demikian. Jika masalah selalu terjadi di perangkat Anda, katakan juga, tetapi jangan mengklaim bahwa hal itu terjadi pada semua orang.

Panduan GitHub untuk membuat isu menjelaskan cara memasukkan judul dan isi yang deskriptif, serta menyebutkan bahwa repositori mungkin menyediakan templat isu. Gunakan templat tersebut jika tersedia. Struktur lisan di bawah ini membantu Anda mengumpulkan fakta sebelum mengisi kolom-kolomnya; struktur ini bukan alasan untuk mengabaikan petunjuk proyek.

Catatan suara dengan lima kolom

Buka draf pribadi yang kosong alih-alih langsung mengirim laporan ke pelacak isu publik. Klik editor dan dikte lima kolom singkat. Mulailah baris baru untuk setiap kolom. Draf pertama Anda sebaiknya terdengar seperti keterangan saksi, bukan catatan rilis yang telah dipoles:

1. Konteks: Apa yang sedang Anda coba lakukan? Sebutkan halaman, fitur, atau operasinya.
2. Langkah: Tindakan apa yang menyebabkan kegagalan? Beri nomor sesuai urutan.
3. Harapan: Hasil apa yang sewajarnya Anda harapkan?
4. Kenyataan: Apa yang terjadi di layar? Kutip pesan kesalahan singkat hanya setelah memeriksanya.
5. Cakupan: Kapan hal itu terjadi, di lingkungan apa, dan apakah Anda dapat mengulanginya?

Berikut templat yang dapat disalin dan ditempel. Ganti setiap bagian dalam tanda kurung siku dengan detail yang Anda amati. Jika suatu kolom belum diketahui, tulis "belum diperiksa" alih-alih mengisinya dengan jawaban yang terdengar masuk akal.

Judul: [tindakan] menyebabkan [hasil yang diamati]
Konteks: Saya sedang mencoba [tujuan] di [fitur/halaman].
Langkah untuk mereproduksi:
1. [kondisi awal yang persis]
2. [tindakan pertama]
3. [tindakan berikutnya]
Harapan: [apa yang seharusnya terjadi]
Kenyataan: [apa yang terjadi, termasuk teks kesalahan yang sudah diperiksa]
Frekuensi: [sekali / kadang-kadang / setiap percobaan di perangkat ini]
Lingkungan: [versi aplikasi, sistem operasi, peramban jika relevan]
Bukti: [tangkapan layar yang aman atau log yang telah disanitasi, jika berguna]

Jangan membaca tanda kurung siku dengan lantang dan berharap hasilnya otomatis menjadi format yang terstruktur. Tulis judul kolom di editor terlebih dahulu, lalu berbicaralah untuk mengisi setiap kolom. Jika Anda memakai papan ketik suara desktop seperti Talkpad di macOS atau Windows, letakkan kursor di draf pribadi dan dikte satu kolom setiap kali. Dengan begitu, Anda lebih mudah berhenti, memeriksa, dan memperbaiki setiap bagian sebelum mengirimnya.

Reproduksi sekali, lalu ceritakan setiap klik

Ingatan mengubah rangkaian langkah menjadi ringkasan. "Saya mengubah pengaturan lalu halamannya macet" mungkin menghilangkan langkah memuat ulang, berpindah akun, atau mengisi formulir yang belum disimpan. Ulangi rangkaiannya jika aman, dengan draf terbuka di samping aplikasi yang bermasalah. Berhentilah sejenak setelah setiap tindakan dan catat apa yang Anda lakukan. Jangan berulang kali memicu bug yang menghapus data atau membebankan biaya hanya demi memperbaiki redaksi.

Buat langkah-langkah yang harfiah: "Buka Pengaturan, pilih bahasa Spanyol, klik Simpan, lalu buka kembali Pengaturan." Hindari "masuk ke pengaturan biasa dan lakukan itu." Jika aplikasi Anda memiliki beberapa tombol Simpan, sebutkan panelnya. Jika bug hanya muncul setelah halaman dimuat ulang, sertakan langkah itu. Rekan yang belum pernah melihat layar Anda seharusnya dapat mengikuti langkah-langkahnya tanpa perlu menanyakan klik yang terlewat.

Anda dapat mendikte ceritanya, tetapi gunakan papan ketik untuk rangkaian karakter yang rentan salah. Model dapat mengubah nama paket menjadi kata-kata umum, mengubah kapitalisasi pada suatu flag, atau menghilangkan tanda minus. Tempel jejak tumpukan atau pesan kesalahan yang telah diperiksa dari aplikasi, alih-alih mengucapkannya. Hal yang sama berlaku untuk versi yang persis, seperti 1.4.12. Lihat panduan kami tentang nama dan istilah teknis untuk kata-kata yang risikonya lebih rendah tetapi tetap perlu ditinjau dengan cermat.

Pisahkan harapan dari kenyataan

Di sinilah laporan menjadi berguna. "Formulirnya gagal" hampir tidak memberi informasi kepada penyelidik. "Setelah saya mengeklik Simpan, konfirmasi muncul, tetapi bahasanya kembali ke bahasa Inggris saat saya membuka kembali Pengaturan" menggambarkan perbedaan yang dapat diamati. Hasil yang diharapkan bisa sama lugasnya: "Bahasa yang disimpan seharusnya tetap bahasa Spanyol saat saya membuka kembali Pengaturan."

Jangan menyelipkan usulan perbaikan ke kolom harapan. "Aplikasi seharusnya memakai cache lain" adalah saran implementasi, bukan hasil yang diharapkan pengguna. Letakkan dugaan apa pun dalam catatan yang ditandai dengan jelas di bagian akhir, tanpa menghilangkan ketidakpastiannya. Rekan Anda mungkin menemukan bahwa penyebabnya adalah respons API, klien yang belum diperbarui, atau sesuatu yang sama sekali lain.

Ketika pengenalan suara salah menangkap kata negasi, makna laporan bisa terbalik. Bandingkan "dialog tidak tertutup" dengan "dialog tertutup." Baca kembali kalimat-kalimat itu di layar sebelum mengirim laporan. Metode pemeriksaan teks kami yang mendahulukan risiko memprioritaskan negasi, angka, dan nama dibanding penyuntingan gaya karena alasan ini.

Tambahkan lingkungan tanpa membuat berkas investigasi berlebihan

Informasi lingkungan minimum yang berguna biasanya mencakup versi aplikasi, sistem operasi, peramban jika bug terjadi di peramban, dan pengaturan fitur yang diperlukan untuk mereproduksinya. Catat apakah Anda dapat mereproduksinya dalam sesi baru atau di perangkat lain hanya jika Anda benar-benar mengujinya. Waktu kejadian atau kondisi jaringan penting jika memengaruhi hasil; jika tidak, detail itu hanya menambah gangguan.

Periksa tangkapan layar sebelum melampirkannya. Nama pengguna, alamat email, token, data pelanggan, dan pratinjau obrolan bisa tersembunyi di sudut-sudut gambar. Pangkas gambar ke area yang relevan atau kaburkan detail sensitif dengan editor tepercaya. Log juga perlu diperiksa. Jika pelacak isu bersifat publik, anggap lampirannya juga akan bersifat publik. Untuk pertanyaan tentang kebijakan tempat kerja, gunakan daftar periksa privasi pengetikan suara kami sebelum mendikte materi rahasia ke alat apa pun.

Talkpad dapat memasukkan draf yang Anda ucapkan ke aplikasi tempat kursor berada, tetapi tidak memverifikasi apakah tangkapan layar aman atau jejak tumpukan benar. Anda harus memeriksanya sendiri. Jika kebijakan perusahaan membatasi pemrosesan suara untuk data insiden, ikuti kebijakan tersebut dan tulis bagian sensitif secara manual.

Penyuntingan dua tahap sebelum mengirim laporan

Tahap pertama berfokus pada kemampuan reproduksi. Mulailah dari kondisi awal yang tercantum dan ikuti langkah-langkah Anda secara harfiah. Apakah kegagalannya muncul? Apakah hasil yang diharapkan dan yang sebenarnya berbeda serta mudah dipahami? Apakah Anda melewatkan langkah masuk akun atau pengaturan yang memengaruhi hasil? Jika Anda tidak dapat mereproduksinya lagi, ubah kolom frekuensi agar mencerminkan hal itu alih-alih menyembunyikan ketidakpastian.

Tahap kedua berfokus pada risiko. Cocokkan penulisan versi dan teks kesalahan dengan sumbernya. Hapus rahasia dari isi laporan dan lampiran. Ganti spekulasi dengan fakta yang dapat diamati, atau tandai sebagai hipotesis. Persingkat pengantar jika menghambat pembaca mencapai langkah-langkahnya. Anda dapat menggunakan perangkat penyuntingan draf hasil dikte ketika draf pertama berupa satu blok ucapan, bukan kolom-kolom yang rapi.

Laporan yang berguna tidak harus panjang. Ada bug yang cukup dijelaskan dalam tiga langkah dan dua kalimat; ada pula yang membutuhkan contoh terkontrol. Hindari menambah isi yang tidak perlu. Tujuannya agar orang lain dapat mereproduksi perilaku tersebut dan memahami mengapa Anda mengharapkan hasil yang berbeda. Jika Anda belum bisa menjelaskan kondisi awalnya, selidiki sedikit lebih jauh sebelum menerbitkan laporan.

Pertanyaan yang sering diajukan

Bisakah saya menggunakan dikte untuk menulis laporan bug?

Bisa. Dikte konteks, langkah reproduksi, serta perilaku yang diharapkan dan yang sebenarnya ke dalam draf pribadi. Ketik dan verifikasi perintah, pesan kesalahan, URL, dan nomor versi secara persis sebelum membagikannya.

Apa saja yang harus disertakan dalam laporan bug?

Sertakan judul yang deskriptif, konteks awal, langkah-langkah berurutan, hasil yang diharapkan, hasil yang sebenarnya, lingkungan yang relevan, dan bukti yang aman jika diperlukan. Ikuti templat isu repositori jika tersedia.

Bagaimana cara melaporkan bug yang tidak dapat saya reproduksi?

Nyatakan bahwa bug terjadi sekali atau sesekali, catat apa yang Anda amati dan lingkungan yang Anda ketahui, serta sebutkan percobaan mana yang tidak berhasil mereproduksinya. Jangan mengisi langkah-langkah yang tidak diketahui dengan tebakan.

Haruskah saya melampirkan log ke isu publik?

Hanya setelah memeriksa apakah log mengandung rahasia dan informasi pribadi. Hapus atau samarkan data sensitif dan bagikan cuplikan sekecil mungkin yang membantu menjelaskan kegagalan. Ikuti aturan insiden dan privasi tim Anda.

Unduh Talkpad gratis – 2.500 kata/minggu pada paket gratis.