Bir dokümantasyon ekibi, sayfanın kendisinde sorarak doğru sayfaları nasıl düzeltti

Bir açık kaynak projesinin iyi bir dokümantasyonu ve gerçek bir sorunu var: kurulum rehberi ince bir şekilde yanlış. Bir adım iki sürüm önce değişti ve şimdi yeni gelenler aynı noktada takılıp kalıyor. İnsanlar bunu fark ediyor — sosyal medyada sızlanmalar ve topluluk sohbetinde kafası karışmış birkaç soru var — ancak sürdürücüler bunların hiçbirine müdahale edemiyor, çünkü şikayetlerin hiçbiri **hangi sayfa** olduğunu söylemiyor. 'Dokümanlarınız güncel değil' demek bir histir, bir hata bildirimi değildir. Bu yüzden yanlış adım aylarca orada duruyor ve başlamaya çalışan her yeni kullanıcıyı sessizce geri çeviriyor. Dokümantasyon şu döngüyle yaşar veya ölür: bir okuyucu kafa karıştırıcı veya yanlış bir paragraf bulur, sürdürücülere tam olarak nerede olduğunu söyler ve sürdürücüler bunu düzeltir. 'Tam olarak nerede' kısmını koparırsanız bütün döngü durur. ## Sorun: konumu olmayan geri bildirim gürültüdür Okuyucular yardım etmeye isteklidir. Size bir sayfanın kafa karıştırıcı olduğunu memnuniyetle söyleyeceklerdir. Yapmayacakları şey ise bu yardımı eyleme dönüştürülebilir hale getirmek için gereken arkeolojidir — URL'yi kopyalamak, doğru iletişim kanalını bulmak, sorunu açıklamak ve hangi bölüm ile hangi sürüm olduğunu not etmek. Bu, dokümanlarınızı denetlemeye değil, aracınızı öğrenmeye çalışan biri için çok fazla adımdır. Bu yüzden ulaşan geri bildirim, onu faydalı kılan tek şeyden, yani konumdan yoksundur. 'API dokümanları yanlış' diye okuyan bir sürdürücünün yüzlerce sayfası vardır ve nereye bakacağına dair hiçbir fikri yoktur. Bir GitHub issue'su yardımcı olur, ancak sıradan bir okuyucunun bir hesabı olmasını, sorun şablonunuzu anlamasını ve bağlamı tamamen dokümanların dışına taşımasını gerektirir — bu, tam olarak küçük, yüksek etkili hataları yakalayan ayaküstü geri bildirimlerin çoğunu filtreleyen bir sürtünmedir. Sonuç garip bir dengesizliktir: birçok okuyucu sorunları fark eder, ancak neredeyse hiçbiri sizin düzeltebileceğiniz bir biçimde bildirilmez. ## Çözüm: sayfa başına bir 'Bir sorun bildir' bağlantısı Her dokümantasyon sayfasının altbilgisine küçük bir **Bu sayfayla ilgili bir sorun bildir** bağlantısı koyun. Bu bir `mailto:` bağlantısıdır ve hilesi, mevcut sayfa yolunu konu ve gövdeye önceden doldurmasıdır. Okuyucu tıklar, e-postası konum zaten yakalanmış olarak açılır ve ekledikleri tek şey neyin yanlış olduğudur. Dokümanlar genellikle bir şablondan veya statik site oluşturucudan oluşturulduğu için yolu otomatik olarak enjekte edebilirsiniz. Şablonlu bir sitede, sayfa değişkenini doğrudan bağlantının içine bırakın: ```html <a href="mailto:[email protected]?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> Bu sayfayla ilgili bir sorun bildir </a> ``` Veya şablonlama olmadan herhangi bir sayfada çalışması için bir satır script ile ayarlayın: ```html <a id="docs-issue" href="#">Bu sayfayla ilgili bir sorun bildir</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:[email protected]' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` Bu sitedeki oluşturucu kodlanmış bağlantıyı üretir; script yalnızca canlı yolu değiştirir. Artık her bildirim konusunda tam sayfanın adını belirtiyor ve bir sürdürücü doğrudan kaynak dosyasına atlayabiliyor. ## Bunun için sayfa içi yöntem neden bir issue tracker'dan daha iyidir Bir issue tracker bir düzeltme için doğru yuvadır, ancak geri bildirim için kötü bir ön kapıdır. Bir hesap, bağlam değişikliği ve sürecinize aşinalık gerektirir — bunlar, bir kod örneğinde sadece bir yazım hatası fark eden sıradan okuyucuyu geri çeviren engellerdir. `mailto:` bağlantısı okuyucularla kafa karışıklığının tam olarak yaşandığı yerde buluşur: sayfada, tek bir tıklamayla, hesap olmadan. Asla bir tracker'a olan yolculuktan sağ çıkamayacak küçük düzeltmelerin uzun kuyruğunu yakalar. İkisi birlikte iyi çalışır. Bildirimler, sayfayla önceden etiketlenmiş olarak e-posta ile gelir; bir sürdürücü onları sınıflandırır ve yalnızca izlemeye değer olanlar için tracker'da issue açar. Önde e-postanın düşük sürtünmesini ve arkada bir tracker'ın titizliğini elde edersiniz. ## Kurulum 1. Sürdürücülerin izlediği `docs@` gibi bir doküman gelen kutusu seçin. 2. Oluşturucuda alıcıyı, 'Docs issue: [sayfa yolu]' şeklinde bir konuyu ve neyin yanlış olduğunu ve neyin yardımcı olacağını soran bir gövdeyi ayarlayın. 3. Bağlantıyı sayfa şablonunuzun altbilgisine ekleyin, yolu oluşturucunuzun sayfa değişkeniyle veya yukarıdaki küçük script ile enjekte edin. 4. Gelen e-postaları 'Docs issue:' konu etiketiyle yönlendirin ki bildirimler tek bir yere düşsün. 5. Döngüyü kapatın: bildirilen bir sayfayı düzelttiğinizde, okuyucuya tek satırlık bir yanıt, bir hata bildirimini iyi niyete dönüştürür. ## Ne kazandırır İlk kazanç **sürdürücünün sorunları bulmak için harcadığı zamandır**. Her bildirim sayfanın adını verdiğinde, dedektiflik işini atlar ve doğrudan düzeltmeye gidersiniz. Eskiden eyleme dökülemeyen 'bir yerlerde bir şeyler yanlış' şeklindeki bir bildirim, iki dakikalık bir düzenlemeye dönüşür. İkincisi **daha az takılıp kalan kullanıcıdır**. Dokümantasyon hataları katlanarak artar: yanlış bir kurulum adımı bir kez başarısız olmaz, birisi onu düzeltene kadar her yeni gelen için başarısız olur. 'Bir okuyucu fark eder' ile 'bir sürdürücü tam olarak nerede olduğunu bilir' arasındaki süreyi kısaltmak, her kötü paragrafın çok daha az insanı geri çevirmesi anlamına gelir. Benimsenerek büyüyen bir araç için, yeni gelenlerin önündeki engelleri kaldırmak büyümedir. Üçüncüsü **geri bildirimin hacmi ve dürüstlüğüdür**. Bildirim yapmak tek bir tıklama aldığından ve hesap gerektirmediğinden, bunu daha fazla okuyucu yapar — asla bir tracker'da issue açmayacak olanlar dahil. Güveni aşındıran küçük, utanç verici hataları duyarsınız ve bunları hâlâ önemliyken duyarsınız. ## Daha da iyi yapın - Yolun yanına **doküman sürümünü veya commit'ini** otomatik olarak doldurun, böylece bir bildirimin yakın zamandaki bir yeniden yazmadan öncesine ait olup olmadığını anlayabilirsiniz. - Bağlantıyı dokümanlarınızdaki **404 sayfalarına** ekleyin, burada eksik bir sayfanın kendisi faydalı bir sinyaldir. - Botların binlerce halka açık sayfadan toplamasını önlemek için adresi **gizlenmiş** tutun. - Varsayılan bir e-posta uygulaması olmayan okuyucular için düz bir adres veya tracker bağlantısı gibi görünür bir alternatif sunun. ## Önemli çıkarımlar - Konumu olmayan doküman geri bildirimi gürültüdür; okuyucular bir tane eklemek için nadiren zahmete girerler. - Sayfa başına bir 'Bir sorun bildir' `mailto:` bağlantısı, tam yolu önceden doldurur, böylece her bildirim eyleme dönüştürülebilir hale gelir. - Sayfa içi e-posta, bir tracker'ın filtrelediği ayaküstü düzeltmeleri yakalar, ardından gerçek düzeltmeler için tracker'ı besler. - Sürdürücüye zaman kazandırır, yeni gelenlerin önündeki engelleri daha hızlı kaldırır ve sessizce güvene mal olan küçük hataları yüzeye çıkarır. Kendi doküman geri bildirim bağlantınızı [oluşturucuda](/#generator) oluşturun veya aşağıdaki kurulumu kopyalayın.