Görsel Hata Raporlamaya Eksiksiz Kılavuz

Her geliştirici o hata raporunu almıştır. "Sayfa garip görünüyor." "Bir hata var." "Çalışmıyor." Ardından üç dakikalık bir ileri geri konuşma başlar: "Hangi sayfa? Ne hatası? Neye tıkladınız?" Hatayı düzeltmek iki dakika sürebilir, ancak onu anlamak on dakika sürer.

Tek bir açıklama eklenmiş ekran görüntüsü, bu sürtüşmenin neredeyse tamamını ortadan kaldırır. Sorun görünür. Konum açık. Adımlar numaralandırılmış. Geliştirici sorunu açar, tam olarak neyin yanlış olduğunu görür ve hemen düzeltmeye başlar.

Bu rehber, görsel hata raporlama hakkında bilmeniz gereken her şeyi kapsar: neden işe yaradığı, nasıl iyi yapılacağı, en çok zaman kazandıran açıklama teknikleri ve hangi araçların kullanılacağı.

Hata Raporları İçin Ekran Görüntüleri Neden Metinden Daha İyidir?

Metin tabanlı hata raporları üç temel sorundan muzdariptir:

Belirsizlik. Ayarlar sayfasındaki düğme çalışmıyor" ifadesi 15 düğmeden herhangi birini ifade edebilir. "Bildirim tercihleri panelindeki gönder düğmesi" bunu daraltır, ancak yine de geliştiricinin oraya gitmesini, düğmeyi bulmasını ve yeniden üretmeye çalışmasını gerektirir. Düğmeyi işaret eden bir ok içeren bir ekran görüntüsü, belirsizliği anında giderir.

Eksik bağlam. Hata bildirenler, ilgili olduğunu düşündükleri şeyleri tanımlar, ki bu genellikle geliştiricinin ihtiyacı olan şey değildir. Bir ekran görüntüsü, hata mesajları, URL, tarayıcı durumu, çevredeki kullanıcı arayüzü öğeleri gibi görünümdeki her şeyi yakalar — bildirenin bunları belirtmeyi düşünüp düşünmediğine bakılmaksızın. Birçok hata, bildirenin hiç bahsetmediği, ekran görüntüsünde görünen bir şeyden teşhis edilir.

Yeniden üretme zorluğu. Tıkladım ve bir hata aldım" ifadesi, bir geliştiricinin sorunu yeniden üretmesine yardımcı olmaz. Her adımı gösteren numaralandırılmış bir dizi ekran görüntüsü — "1. Ayarları açtım, 2. Dışa aktara tıkladım, 3. Bu hata iletişim kutusunu aldım" — belirsiz bir raporu yeniden üretilebilir bir test durumuna dönüştürür.

Microsoft ve Zürih Üniversitesi'nden yapılan araştırmalar, görsel ekleri olan hata raporlarının yalnızca metin içeren raporlara göre %13-18 daha hızlı çözüldüğünü bulmuştur. Haftada yüzlerce hata raporu alan büyük kuruluşlarda, bu zaman tasarrufu muazzamdır.

Etkili Bir Hata Raporu Ekran Görüntüsünün Anatomisi

Tüm ekran görüntüleri eşit yaratılmamıştır. Ham, açıklama eklenmemiş bir ekran görüntüsü hiçbir şeyden iyidir, ancak açıklama eklenmiş bir ekran görüntüsü ham olandan daha iyidir. İşte iyi görsel hata raporlarını harika olanlardan ayıran şey:

1. Doğru Alanı Yakalayın

Tam ekran yakalama yerine bölge yakalama kullanın. Amaç, sorunu bulmak için yeterli bağlamı göstermek, ancak izleyicinin onu aramak zorunda kalacağı kadar çok olmamaktır. Bir kullanıcı arayüzü hatası için, bileşeni ve yakın çevresini yakalayın. Bir hata iletişim kutusu için, neyin tetiklediğini gösterecek kadar arka planla birlikte iletişim kutusunu yakalayın.

2. Sorunu İşaret Edin

Sorunun tam olarak nerede olduğunu bir ok veya daire ile belirtin. Hata size bariz görünse bile, geliştiricinin açık on başka sorunu olabileceğini unutmayın. Bir ok, bildirdiğiniz şey hakkındaki belirsizliği ortadan kaldırır.

3. Metin Açıklamalarıyla Bağlam Ekleyin

Kısa bir metin etiketi birçok karışıklığı önleyebilir. Yanlış bir rengin yanına "Beklenen: mavi. Gerçek: yeşil". Bir yazım hatasının yanına "Bu 'Export' demeli, 'Expprt' değil". Yavaş bir bileşenin üzerine "Bu 8 saniye sonra yükleniyor". Etiketleri kısa tutun — en fazla bir cümle.

4. Adımlarınızı Numaralandırın

Yeniden üretmek için bir dizi eylem gerektiren hatalar için numaralandırılmış açıklamalar paha biçilmezdir. "Adım 1: Ayarlar'a tıklayın. Adım 2: Koyu modu açın/kapatın. Adım 3: En alta kaydırın. Adım 4: Bu öğe kaybolur." Ekran görüntüsündeki her sayı bir eyleme karşılık gelir ve görsel bir yeniden üretim rehberi oluşturur.

5. Hassas Bilgileri Gizleyin

Bir ekran görüntüsünü herhangi bir hata izleyiciye eklemeden önce, görünür hassas verileri kontrol edin: e-posta adresleri, API keys, tokens, kişisel kullanıcı verileri, dahili URL'ler veya veritabanı içeriği. Bir hata raporunda olmaması gereken her şeyi gizlemek için bulanıklaştırma veya pikselleştirme aracını kullanın. Bu, özellikle herkese açık GitHub sorunlarına düşebilecek ekran görüntüleri için kritik öneme sahiptir. Ekran görüntüsü güvenliği rehberimiz bunu derinlemesine ele almaktadır.

Hata Türüne Göre Açıklama Teknikleri

Düzen ve CSS Hataları

Hizalanmamış öğelerin etrafına dikdörtgenler çizin. Beklenen hizalamayı göstermek için çizgiler kullanın. Belirli değerlerle metin etiketleri ekleyin: "Beklenen 16 piksel boşluk, gerçek 0 piksel." DevTools'u açıp hesaplanan stilleri yakalayabiliyorsanız, bunu ikinci bir ekran görüntüsü olarak ekleyin.

Fonksiyonel Hatalar

Yeniden üretme adımlarını numaralandırın. Bozuk eylemden önceki ve sonraki durumu yakalayın. Bir hata mesajı varsa, tamamen görünür olduğundan ve bir dikdörtgenle vurgulandığından emin olun. Orada hatalar görüyorsanız tarayıcı konsolunu ekleyin — geliştiriciler JavaScript hataları, ağ sorunları ve CORS sorunları arayacaktır.

İçerik ve Metin Hataları

Yanlış metni daire içine alın. Beklenen içerikle bir metin açıklaması ekleyin. Yazım hataları için, belirli kelimeyi işaret eden bir ok yeterlidir. Eksik içerik için, içeriğin görünmesi gereken yere bir dikdörtgen çizin ve "Eksik: [açıklama]" olarak etiketleyin.

Performans Hataları

Performans hatalarını görsel olarak yakalamak zordur. En iyi seçeneğiniz, yavaş istekleri gösteren tarayıcının Network sekmesini veya uzun görevleri gösteren Performance sekmesini ekran görüntüsü almaktır. Zaman damgalarıyla açıklama ekleyin: "Bu istek 8.2 saniye sürüyor." Akıcı olmayan animasyonlar için, bir ekran kaydı bir ekran görüntüsünden daha faydalıdır.

Tarayıcılar Arası Hatalar

İki ekran görüntüsü alın: biri çalıştığı tarayıcıdan, diğeri bozuk olduğu tarayıcıdan. Bunları yan yana veya dikey olarak etiketlerle istifleyin: "Chrome 120 (doğru)" ve "Firefox 121 (bozuk)." Görsel fark, sorunu hemen açık hale getirir.

Ekipler İçin En İyi Uygulamalar

Ekran görüntüsü aracınızı standartlaştırın. Ekipteki herkes aynı aracı kullandığında, ekran görüntüleri tutarlı görünür ve herkes hangi açıklama özelliklerinin mevcut olduğunu bilir. Maxisnap Maxisnap ekipler için iyi bir seçimdir çünkü açıklama araçları tüm yaygın kullanım durumlarını (oklar, sayılar, metin, bulanıklık) kapsar ve kaynak kullanımı konusunda kimsenin şikayet etmeyeceği kadar hafiftir.

Açıklama kuralları oluşturun. "Bu hata" için kırmızı oklar. "Beklenen davranış" için yeşil oklar. "İlgili bağlam" için mavi dikdörtgenler. Yeniden üretme adımları için numaralandırılmış daireler. Bu kuralların resmi olarak belgelenmesi gerekmez — beş dakikalık bir ekip tartışması yeterlidir. Bir kez oluşturulduğunda, her hata raporu hem oluşturulması hem de okunması daha hızlı hale gelir.

Ortam bilgilerini ekleyin. Ekran görüntülerinizde URL çubuğunu, tarayıcı sürümünü veya işletim sistemi göstergesini yakalamayı alışkanlık haline getirin. Bu bağlam genellikle bölge yakalamalarından kesilir ancak bir hatayı yeniden üretmek ile bir saat harcamak arasındaki fark olabilir. Alternatif olarak, ortam ayrıntılarını hata raporunun metnine ekran görüntüsüyle birlikte ekleyin.

Dosya ekleri yerine yükleme bağlantıları kullanın. Bir Jira yorumundaki ekran görüntüsü bağlantısı anında yüklenir. 5 MB'lık bir PNG eki, bir tıklama ve indirme gerektirir. Gibi araçlar Maxisnap otomatik yükleme ile otomatik olarak paylaşılabilir bağlantılar oluşturur, bu da bir ekran görüntüsü URL'sini herhangi bir hata takip sistemine, Slack kanalına veya e-postaya yapıştırmayı çok kolay hale getirir. SFTP yüklemesini kurma beş dakika sürer ve her yakalama için size kalıcı bir bağlantı sağlar.

Araç Önerileri

En iyi görsel hata raporlama aracı üç özelliğe sahiptir: kısayol tuşuyla hızlı yakalama, anında açıklama ekleme (ayrı bir düzenleyiciye geçiş yok) ve hızlı paylaşım (yükleme veya panoya kopyalama).

• Maxisnap — Anında açıklama ekleme ve sunucuya yükleme özellikli, hafif, klavye odaklı yakalamaya ihtiyaç duyan ekipler için en iyisi. Numaralı adımlar ve bulanıklaştırma dahil 11 açıklama aracı. Kişisel kullanım için ücretsiz.
• Snagit — Üstün açıklama özelliklerini isteyen ve 62,99 $ ödemeye istekli kuruluşlar için en iyisi. Adım numaralandırma ve akıllı taşıma araçları dokümantasyon için mükemmeldir.
• ShareX — Maksimum yapılandırılabilirlik isteyen ve karmaşıklıktan çekinmeyen geliştiriciler için en iyisi. Ücretsiz ve açık kaynaklı.
• Loom — Ekran görüntüleri yeterli olmadığında ve hızlı bir video anlatımına ihtiyacınız olduğunda en iyisi. Ekran kaydı ve anlatımın birleşimi, karmaşık hatalar için güçlüdür. (Monosnap'ten geliyorsanız, şuraya bakın: Maxisnap ve Monosnap karşılaştırmamızı okuyun.)

İyi Hata Ekran Görüntülerinin Yatırım Getirisi (ROI)

Görsel hata raporlama sadece güzel bir uygulama değil; geliştirme hızına ölçülebilir bir etkisi vardır. Matematiği düşünün:

• Yalnızca metin içeren bir hata raporu, iş başlamadan önce ortalama 2-3 açıklama alışverişi gerektirir: ~15 dakikalık birikmiş bekleme süresi
• Açıklamalı bir ekran görüntüsü bu alışverişleri ortadan kaldırır: hata başına ~15 dakika tasarruf
• Haftada 50 hata bildiren bir ekip, haftalık ~12,5 saat açıklama süresinden tasarruf eder
• Bir yıl içinde, bu 600 saatin üzerinde geliştirici zamanının geri kazanılması demektir

Ve bu hesaplama yalnızca açıklama için harcanan zamanı kapsar. Odaklanma kesintisi maliyetini içermez — her açıklama alışverişi hem raporlayıcının hem de geliştiricinin bağlam değiştirmesini gerektirir ve her biri ek 10-15 dakikalık üretken zamana mal olur.

Başlarken

Hata raporlarınızda henüz açıklamalı ekran görüntüleri kullanmıyorsanız, bugün başlayın. Açıklama desteği olan bir ekran görüntüsü aracı indirin, beş dakika öğrenerek klavye kısayollarıve bir paragraf açıklama yazmak yerine bir sonraki hata raporunuzu açıklama ekleyerek deneyin.

Bir geliştirici "Hangi düğmeyi kastettiğinizi açıklayabilir misiniz?" yerine "Düzeltildi, teşekkürler — harika ekran görüntüsü" diye yanıt verdiğinde, bir daha asla yalnızca metin içeren hata raporlarına geri dönmeyeceksiniz.