İnsanların takip ettiği bir changelog sayfası nasıl kurulur

Bir changelog sayfası, biri ona geri dönecekse kurmaya değer. Bu, sadece ona sahip olmaktan daha yüksek bir çıta, ve çoğunun düştüğü çıta budur: var olan, footer’da bağlantısı verilen, sıçramalarla güncellenen ve bir olay sırasında dışında kimsenin ziyaret etmediği bir sayfa. İkisini ayıran kararlar hiçbir şey yazılmadan önce verilir, ve çoğunlukla sayfanın nerede yaşadığı ve aynı içerikten başka ne üretildiği hakkındadır.

Changelog sayfası nedir?

Bir üründe neyin değiştiğinin, size ait bir URL’de herkese açık, tarihli listesidir. Aynı kayıtların görünebileceği beş yüzeyden biridir, ve yararlı soru hangisini seçeceğiniz değil, hangisinin kanonik olduğu ve hangilerinin ondan üretildiğidir.

Kanonik bir kaynak seçin, bir kez yayınlayın, ve gerisini üretin. Sayfayı ve widget’ı ayrı ayrı elle sürdüren ekipler, uyuşmayan iki metinle sonuçlanır, ve uyumsuzluğu bir müşteri keşfeder.

Bir changelog sayfası nerede yaşamalı?

Kendi domaininizde, kararlı bir yolda, her kayıt bir fragment veya kendi yoluyla ayrı ayrı adreslenebilir şekilde. Üç yaygın yerleşim bir ana site yolu, bir alt domain, ve dokümantasyonun bir bölümüdür. Ana sitedeki bir yol, lehine değil aleyhine tartışılması gereken varsayılan seçimdir: sitenin otoritesini devralır, ekstra sertifika veya DNS gerektirmez, ve sayfayı diğer her şeyle aynı navigasyonda tutar.

Bir alt domain, sayfa pazarlama sitesinden farklı bir sistem tarafından sunulduğunda ve aksi halde proxy yapıyor olacağınızda doğru cevaptır. Bedeli, otoriteyi ayrı biriktirmesidir. Changelog’u dokümanlara koymak, kitle geliştiricilerse doğrudur, API changelog’da ele alınan nedenle: okuyucu genellikle zaten oradadır.

Seçimden daha önemli olan, kayıtların ayrı ayrı bağlanabilir olmasıdır. İnsanlar olay incelemelerinde ve dahili biletlerde kayıtlara bağlantı verir, ve sadece “changelog, aşağı kaydır” olarak bağlanabilen bir kayıt yerine ekran görüntüsü olarak yapıştırılır.

Bir changelog sayfası neye ihtiyaç duyar?

Beş şey, ve ilk ikisinde çoğu sayfa başarısız olur. Değişiklik başına tarihli bir kayıt, en yeni önce. İlgilenilen türü taramak için kayıt başına bir kategori veya etiket. Kayıt başına bir permalink. Bir abonelik yolu. Elli civarı kayıttan sonra bir arama veya filtre.

Gerisi opsiyoneldir. Ekran görüntüleri yardımcı olur ve bakım maliyeti çıkarır. Yazar isimleri bazı ürünlerde güven inşa eder, bazılarında gürültü çıkarır. Sürüm numaraları bir API’nin çağıranları için önemlidir, neredeyse başka hiç kimse için değil. Keep a Changelog, kendinizinkini icat etmek için sebebiniz yoksa etiketler için makul bir varsayılan sunar, ve merkezi kuralı, gerisini atsanız bile saklamaya değer olandır: günlük insanlar içindir.

Ürününüz sürekli yayınlıyorsa sürüme göre değil tarihe göre gruplayın. “Bu, dokuzuncu gündeki olayımızdan önce mi sonra mı” diye tarayan bir okuyucu bir tarih arar, ve sürüm numarasına göre düzenlenmiş bir sayfa onu hesap yapmaya zorlar.

Sayfa mı, uygulama içi widget mı?

İkisi de, tek bir kaynaktan. Sayfa aramanın, bağlantıların ve uzun kaydın yaşadığı yerdir. Widget, sayfayı hiç ziyaret etmeyecek çoğunluğa ulaşma yolunuzdur, ve çalışır çünkü zaten kullandıkları üründe görünür.

Widget’ın başarısızlığı kesintidir. Her kayıt için dikkat isteyen bir rozet bir hafta içinde kalıcı olarak reddedilir, ki bu size gerçekten önemli olan kayıt için kanalı kaybettirir. Okuyucunun son baktığından beri okunmamışları sayın, ilk ziyarette sayacı sessizce başlatın ki kimse bir yıllık geçmişin rozetiyle karşılanmasın, ve okuyucunun onu kendisi için açmak yerine kendi açmasına izin verin.

Bir changelog sayfası nasıl makine tarafından okunabilir hale getirilir?

Aynı kayıtları akış olarak da yayınlayın. Bir JSON akışı, onu kodda tüketen herhangi biri için en düşük sürtünmeli seçenektir, ve bir RSS akışı, bir okuyucuda abone olan bir geliştiricinin beklediği şeydir. Kayıtlar elle yazılmış HTML yerine yapılandırılmış veri olduğunda ikisi de az maliyetlidir, ki bu kanonik kopyayı yapılandırılmış tutmanın gerçek gerekçesidir.

Sayfayı işaretleyin de. Kayıtlar tarihi ve başlığı olan eserlerdir, ve schema.org kelime dağarcığını sağlar. Permalink’lerle aynı nedenle değerlidir: sayfayı bir tarayıcı olmayan şeyler tarafından, müşterinin kendi release süreci dahil, kullanılabilir hale getirir. Bunların hiçbiri, altta yatan kayıtlar en başından beri hiç yapılandırılmış veri olmadıysa çalışmaz; changelog dosya formatları, bu akışın ve bu işaretlemenin gerçekte üretildiği doğruluk kaynağı olarak Markdown, JSON ve YAML’in her birinin neye mal olduğunu ele alır.

Bir changelog sayfası SEO’ya yardımcı olur mu?

Dolaylı ve yavaş şekilde. Tek tek kayıtlar nadiren sıralanır, çünkü kimsenin yazmadığı bir sorguyu hedeflemezler. Sayfa yerini bağlantılar yoluyla kazanır: kayıtlar destek yanıtlarında, forumlarda ve olay analizlerinde alıntılanır, ve o bağlantılar size ait bir URL’de birikir. İki yıl boyunca haftalık güncellenen bir sayfa, ait olduğu ürün için de güvenilir bir tazelik sinyalidir.

İşe yaramayan şey, kayıtları içerik pazarlaması gibi ele almaktır. Uzunluk için üç paragrafa şişirilmiş bir kayıt, gerçek işinde daha kötüdür, ki bu iş bir okuyucuya kullandığı bir şeyin değişip değişmediğini tek cümlede söylemektir. Changelog’un aramayı desteklemesini istiyorsanız, çabayı permalink’lere, akışa ve ona giden dahili bağlantılara koyun, ve kayıtları kısa tutun. Kendi changelog örnekleri sayfamız bu dengeyi doğru yakalayan sayfaları toplar.

İnsanlar nasıl abone olur?

Onlara zaten kullandıkları yolları verin: geliştiriciler için bir RSS veya JSON akışı, sadece önemli olanları duymak isteyenler için e-posta, ve ikisini de asla yapmayacak herkes için uygulama içi widget. Varsaymak yerine ne duymak istediklerini sorun, çünkü breaking change isteyen ve metin düzeltmeleri alan bir okuyucu ikisinden de abonelikten çıkar.

En son eklenecek yol döngüyü kapatan yoldur. Bir kayıt belirli bir kişinin talep ettiği şeyi çözdüğünde, sayfayı okumasını ummak yerine bunu ona doğrudan söyleyin. changeloop’ta kayıt aynı anda sayfa, akış ve widget üzerinde yayınlanır, ve widget geri bildirimi pull request’in kapattığı GitHub issue’suna dönüşen kişi o issue’da kayda bağlantıyla bilgilendirilir ve kaydı widget’ta görür. Mekanik herhangi bir abonelikle aynıdır; fark, alıcının zaten sormuş olmasıdır. Bu, geri bildirim döngüsünü changelog tarafından kapatma’da detaylandırılan argümandır.

FAQ

Changelog sayfası bir alt domainde mi, bir yolda mı olmalı? Varsayılan olarak ana sitedeki bir yol, çünkü sitenin otoritesini devralır ve ekstra altyapı gerektirmez. Farklı bir sistem sayfayı sunduğunda bir alt domain haklı çıkar.

Sayfa aynı anda kaç kayıt göstermeli? Bir ekranı doldurmaya yeter kadar ve daha fazlası değil, ardından sayfalama. Bir belgeye iki yıllık geçmiş yüklemek yavaştır ve en yeni kaydı bulmayı zorlaştırır.

Eski kayıtlar hiç silinmeli mi? Hayır. Sitenizin dışından alıntılanırlar ve bağlantılar bozulur. Bir kaydı yerinde bir notla düzeltin, ve URL’yi canlı tutun.

Sayfada her değişiklik görünmeli mi? Sadece bir kullanıcının fark edebileceği olanlar. Dahili refactor’ları kaydeden bir sayfa okuyucuları gözden geçirmeye alıştırır, ve gözden geçirilen bir sayfa acil bir şey taşıdığı gün başarısız olur.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Changelog örnekleri, Geliştirici dokümantasyonu