Başkalarının Yeniden Oluşturabileceği Bir Hata Raporu Nasıl Dikte Edilir

“Yine bozuldu” dürüst bir hata bildirimidir. Ama bu bildirime dayanarak sorunu gidermek zordur. Sorun takip sistemini açtığınızda tam olarak hangi ekranın, düğmenin ve sonucun söz konusu olduğu zihninizde birbirine karışmış olur. Hata raporunu dikte etmek, ayrıntılar henüz tazeyken onları kaydetmenizi sağlayabilir; ancak bunun için konuşmaya başlamadan önce anlatımınıza bir yapı kazandırmanız gerekir.

Bu kısa iş akışı, gözlemlediğiniz bir hatayı başka birinin yeniden oluşturabileceği bir rapora dönüştürmenize yardımcı olur. Kendi projenizi test ederken, iş yerinde sorun bildirirken veya açık kaynaklı bir aracın bakımına katkıda bulunurken kullanabilirsiniz. Kesin komutları yine yazarak girmeniz ve son raporu kontrol etmeniz gerekir. Sesinizi kanıt uydurmak için değil, yaşananları anlatmak için kullanın.

Teşhisle değil, hatayla başlayın

Başlık bir teori öne sürdüğünde hata raporları yanlış yöne kayar: “Veritabanı önbelleği bozuk.” Haklı olabilirsiniz, ancak sorunu inceleyen kişinin önce gözleminizi bilmesi gerekir. Daha iyi bir başlık, eylemi ve sonucu belirtir: “Taslağı kaydetmek, Ayarlar'da seçilen dili sıfırlıyor.” Bu, nedene ilişkin teorinizi kabul etmeden de test edilebilir.

Dikte ederken de aynı kural işe yarar. Önce tamamlamaya çalıştığınız işi bir cümleyle, ardından yazılımın bunun yerine ne yaptığını bir cümleyle anlatın. Haftanızın uzun hikâyesiyle veya hangi alt sistemin bozulduğuna dair tahminle başlamayın. Sorun ara sıra yaşanıyorsa bunu söyleyin. Kendi cihazınızda her seferinde oluyorsa bunu da belirtin, ancak herkesin aynı sorunu yaşadığını iddia etmeyin.

GitHub'ın sorun oluşturma kılavuzu, açıklayıcı bir başlık ve içerik girilmesini anlatır; ayrıca bir deponun sorun şablonu sunabileceğini belirtir. Varsa bu şablonu kullanın. Aşağıdaki konuşma yapısı, alanları doldurmadan önce olguları toplamanıza yardımcı olur; projenin kendi yönergelerini göz ardı etmek için bir gerekçe değildir.

Beş alanlı sesli not

Doğrudan herkese açık bir sorun takip sistemine göndermek yerine boş, özel bir taslak açın. İmleci düzenleyiciye yerleştirip beş kısa alanı dikte edin. Aralarında yeni satır bırakın. İlk taslağınız özenle hazırlanmış bir sürüm notu gibi değil, bir tanığın anlatımı gibi olmalıdır:

1. Bağlam: Ne yapmaya çalışıyordunuz? Sayfayı, özelliği veya işlemi belirtin.
2. Adımlar: Hangi eylemler hataya yol açtı? Bunları sırayla numaralandırın.
3. Beklenen: Makul olarak nasıl bir sonuç bekliyordunuz?
4. Gerçekleşen: Ekranda ne oldu? Kısa bir hata mesajını ancak doğruladıktan sonra alıntılayın.
5. Koşullar: Ne zaman, hangi ortamda oldu ve tekrarlayabiliyor musunuz?

İşte kopyalayıp yapıştırabileceğiniz bir şablon. Köşeli parantez içindeki her ifadeyi gözlemlediğiniz bir ayrıntıyla değiştirin. Bir alanı bilmiyorsanız makul görünen bir yanıt uydurmak yerine “kontrol edilmedi” yazın.

Başlık: [eylem], [gözlemlenen sonuca] yol açıyor
Bağlam: [özellikte/sayfada] [amacı] gerçekleştirmeye çalışıyordum.
Yeniden oluşturma adımları:
1. [kesin başlangıç durumu]
2. [ilk eylem]
3. [sonraki eylem]
Beklenen: [ne olması gerektiği]
Gerçekleşen: [doğrulanmış hata metni dahil ne olduğu]
Sıklık: [bir kez / bazen / bu cihazdaki her denemede]
Ortam: [uygulama sürümü, işletim sistemi, ilgiliyse tarayıcı]
Kanıt: [yararlıysa güvenli ekran görüntüsü veya hassas verileri temizlenmiş günlük]

Köşeli parantezleri sesli okuyup bunların yapılandırılmış biçimlendirmeye dönüşmesini beklemeyin. Önce başlıkları düzenleyiciye yazın, ardından her alanın içeriğini söyleyin. macOS veya Windows üzerinde Talkpad gibi bir masaüstü sesli klavye kullanıyorsanız imleci özel taslağınıza yerleştirin ve alanları tek tek dikte edin. Böylece yayımlamadan önce durup her parçayı incelemek ve düzeltmek kolaylaşır.

Bir kez yeniden oluşturun, ardından tıklamaları anlatın

Bellek, bir eylem dizisini özete dönüştürür. “Bir ayarı değiştirdim ve sayfa çöktü” ifadesi sayfayı yenilemeyi, hesap değiştirmeyi veya kaydedilmemiş formu atlayabilir. Güvenliyse ilgili uygulamanın yanında taslağınız açıkken adımları tekrarlayın. Her eylemden sonra durup ne yaptığınızı kaydedin. Sırf ifadeyi iyileştirmek için veri silen veya para tahsil eden bir hatayı tekrar tekrar tetiklemeyin.

Adımları somut yazın: “Ayarlar'ı açın, İspanyolcayı seçin, Kaydet'e tıklayın, Ayarlar'ı yeniden açın.” “Her zamanki tercihlere girip gerekeni yapın” demeyin. Uygulamada birden fazla Kaydet düğmesi varsa panelin adını belirtin. Hata ancak sayfa yeniden yüklendikten sonra ortaya çıkıyorsa bu adımı ekleyin. Ekranınızı hiç görmemiş bir iş arkadaşınız, eksik tıklamayı sormak zorunda kalmadan adımları uygulayabilmelidir.

Anlatımı dikte edebilirsiniz, ancak tek bir karakterin bile önemli olduğu dizeleri klavyeyle girin. Bir model paket adını sıradan sözcüklere çevirebilir, bir komut satırı seçeneğinin büyük-küçük harflerini değiştirebilir veya eksi işaretini atlayabilir. Doğrulanmış yığın izini ya da hata mesajını söylemek yerine uygulamadan kopyalayıp yapıştırın. 1.4.12 gibi kesin sürüm numaraları için de aynısı geçerlidir. Daha az riskli olsa da dikkatle gözden geçirilmesi gereken sözcükler için adlar ve teknik terimler kılavuzumuza bakın.

Beklenen ile gerçekleşeni ayırın

Raporun yararlı hâle geldiği nokta burasıdır. “Form başarısız oldu” ifadesi sorunu inceleyen kişiye neredeyse hiçbir şey söylemez. “Kaydet'e tıkladıktan sonra onay göründü, ancak Ayarlar'ı yeniden açtığımda dil tekrar İngilizceye dönmüştü” ifadesi ise gözlemlenebilir bir uyuşmazlığı anlatır. Beklenen sonuç da aynı açıklıkta olabilir: “Ayarlar'ı yeniden açtığımda kayıtlı dil hâlâ İspanyolca olmalı.”

Beklenen sonuç alanına önerdiğiniz çözümü yerleştirmeyin. “Uygulama farklı bir önbellek kullanmalı” ifadesi, kullanıcının görebileceği bir beklenti değil, uygulamaya yönelik bir öneridir. Varsayımınız varsa belirsizliğini koruyarak raporun sonunda açıkça işaretlenmiş bir not olarak ekleyin. İş arkadaşınız nedenin bir API yanıtı, eski bir istemci veya bambaşka bir şey olduğunu bulabilir.

Konuşma tanıma bir olumsuzluğu yanlış aktarırsa rapor kendi anlamını tersine çevirebilir. “İletişim kutusu kapanmadı” ile “iletişim kutusu kapandı” ifadelerini karşılaştırın. Göndermeden önce bu cümleleri ekranda yeniden okuyun. Risk öncelikli düzeltme yöntemimiz bu nedenle olumsuzlukları, sayıları ve adları üslup düzeltmelerinden önce ele alır.

Adli inceleme dosyası hazırlamadan ortam bilgisi ekleyin

Yararlı asgari ortam bilgisi genellikle uygulama sürümü, işletim sistemi, hata tarayıcıda ortaya çıkıyorsa tarayıcı ve yeniden oluşturmak için gereken özellik ayarlarıdır. Temiz bir oturumda veya başka bir cihazda sorunu yeniden oluşturup oluşturamadığınızı yalnızca gerçekten test ettiyseniz belirtin. Zaman damgası veya ağ koşulu sonucu etkiliyorsa önemlidir; aksi takdirde gereksiz ayrıntı oluşturur.

Eklemeden önce ekran görüntüsünü inceleyin. Kullanıcı adları, e-posta adresleri, belirteçler, müşteri kayıtları ve sohbet önizlemeleri köşelerde gizlenmiş olabilir. İlgili bölgeyi kırpın veya güvenilir bir düzenleyiciyle hassas ayrıntıları bulanıklaştırın. Günlükleri de aynı özenle inceleyin. Sorun takip sistemi herkese açıksa ekin de herkese açık olacağını varsayın. İş yeri politikasıyla ilgili sorular için herhangi bir araca gizli bilgileri dikte etmeden önce sesle yazma gizlilik kontrol listemize başvurun.

Talkpad, dikte ettiğiniz taslağı imlecinizin bulunduğu uygulamaya aktarabilir; ancak ekran görüntüsünün güvenli olduğunu veya yığın izinin doğru olduğunu doğrulamaz. Bunları sizin kontrol etmeniz gerekir. Şirket politikası olay verileri için konuşma işlemeyi kısıtlıyorsa politikaya uyun ve hassas kısımları elle yazın.

Göndermeden önce iki aşamalı düzenleme

İlk aşamada yeniden oluşturulabilirliği kontrol edin. Belirttiğiniz başlangıç durumundan başlayıp adımlarınızı harfiyen izleyin. Hata ortaya çıkıyor mu? Beklenen ve gerçekleşen sonuçlar farklı ve anlaşılır mı? Oturum açma adımını veya sonucu değiştiren bir ayarı atladınız mı? Sorunu tekrar oluşturamıyorsanız belirsizliği gizlemek yerine sıklık alanını buna göre değiştirin.

İkinci aşamada riskleri kontrol edin. Sürüm dizelerini ve hata metnini kaynaklarıyla karşılaştırın. Açıklamadan ve eklerden gizli bilgileri kaldırın. Varsayımları gözlemlenebilir olgularla değiştirin veya bunları hipotez olarak işaretleyin. Giriş bölümü adımlara geçişi geciktiriyorsa kısaltın. İlk taslak düzenli alanlar yerine kesintisiz bir konuşma bloğu hâlinde geldiyse dikte edilmiş taslakları düzenleme araç setinden yararlanabilirsiniz.

Yararlı bir raporun uzun olması gerekmez. Bazı hatalar için üç adım ve iki cümle yeterlidir; diğerleri kontrollü bir örnek gerektirir. Gereksiz ayrıntı eklemeyin. Amaç, başka birinin davranışı yeniden oluşturabilmesi ve neden farklı bir sonuç beklediğinizi anlayabilmesidir. Başlangıç durumunu açıklayamıyorsanız yayımlamadan önce biraz daha araştırın.

Sık sorulan sorular

Hata raporu yazmak için dikte kullanabilir miyim?

Evet. Bağlamı, yeniden oluşturma adımlarını ve beklenen ile gerçekleşen davranışı özel bir taslağa dikte edin. Paylaşmadan önce kesin komutları, hata mesajlarını, URL'leri ve sürüm numaralarını elle yazıp doğrulayın.

Bir hata raporunda neler olmalı?

Açıklayıcı bir başlık, başlangıç bağlamı, sıralı adımlar, beklenen sonuç, gerçekleşen sonuç, ilgili ortam bilgileri ve gerekiyorsa güvenli kanıtlar ekleyin. Depo bir sorun şablonu sunuyorsa ona uyun.

Yeniden oluşturamadığım bir hatayı nasıl bildirebilirim?

Hatanın bir kez mi yoksa aralıklı olarak mı yaşandığını belirtin, gözlemlediklerinizi ve bildiğiniz ortam bilgilerini kaydedin, hangi denemelerde sorunu yeniden oluşturamadığınızı söyleyin. Bilinmeyen adımları tahminlerle doldurmayın.

Herkese açık bir soruna günlük eklemeli miyim?

Yalnızca gizli bilgiler ve kişisel veriler açısından kontrol ettikten sonra. Hassas verileri kaldırın veya karartın; hatayı açıklamaya yardımcı olan en küçük bölümü paylaşın. Ekibinizin olay ve gizlilik kurallarına uyun.

Talkpad'i ücretsiz indirin – ücretsiz planda haftada 2.500 kelime.