İnsanların gerçekten okuduğu release notes nasıl yazılır

İnsanların okuduğu release notes yazmak için, her girdide tek bir soruyu cevaplayın: okuyucu şimdi neyi daha önce yapamadığı bir şeyi yapabiliyor, ve bunun için ne yapması gerekiyor. Bir son tarihi olan her şeyi en başa koyun, kimin etkilendiğini belirtin, doğruysa “hiçbir işlem gerekmiyor” deyin, ve söyleyecek bir şeyi olmayan sürümleri atlayın. Bu sayfadaki diğer her şey bu kuralın uygulanmasıdır.

Hata düzeltmeleri ve performans iyileştirmeleri.

Her ürün bunu bir kere yayımlamıştır. Sebep nadiren tembelliktir: bu, release notes içeriden, diff’te iki hafta geçirmiş ve artık hangi kısımların bir yabancının umurunda olacağını göremeyen biri tarafından yazıldığında ortaya çıkan şeydir. Daha iyi bir üslup bunu düzeltmez; soruyu cevaplamak düzeltir.

Release notes neleri içermeli?

Release notes, bahsedilmeye değer her değişiklik için şunları içermeli: okuyucunun şimdi ne yapabildiği, kimi etkilediği, ne yapması gerektiği (bu “hiçbir şey” olsa bile) ve son tarihi olan her şeyin ne zaman yürürlüğe girdiği. İç ticket numaralarını, sadece ekibin kullandığı bileşen adlarını, veya tek başlık olarak bir sürüm numarasını içermemeli.

Bir release note ile bir changelog girdisi arasındaki ayrım bu listeyi mümkün kılar: changelog her şeyi tutar, böylece notlar bir şeyleri dışarıda bırakabilir. Her girdi türünün açıklamalı örnekleri release notes örnekleri yazısında toplanmıştır.

Her girdinin cevapladığı soru

Okuyucu şimdi daha önce yapamadığı neyi yapabiliyor, ve bunun için ne yapması gerekiyor?

Bir girdi bunu cevaplayamıyorsa, changelog’a aittir, release notes’a değil. İki yarı da önemlidir. İlk yarı değerdir. İkinci yarı ekiplerin unuttuğu, ve eksik olduğunda destek ticket’ları üreten kısımdır.

Gerçek iş yapan ikinci yarıdan iki örnek:

• “Mevcut webhook’lar 1 Kasım’a kadar çalışmaya devam edecek. Bu tarihten sonra imzasız payload’lar reddedilecek.”
• “Hiçbir işlem gerekmiyor. Mevcut exportlar bir sonraki açışınızda otomatik olarak yeniden kodlanacak.”

İkincisi açıkça “hiçbir işlem gerekmiyor” diyor. Bu cümle her seferinde yazılmaya değer, çünkü onu bulamayan bir okuyucu en kötüsünü varsayar.

Release notes nasıl sıralanmalı?

Onları okuyucu için sonuca göre sıralayın, asla değişen sistem parçasına göre değil. API, panel, mobil ve altyapıya göre gruplamak sizin organizasyon şemanızdır, okuyucunun sorunu değil.

1. Breaking change’ler ve son tarihi olan her şey. Küçük olsa bile her zaman ilk sırada. Bir okuyucu bir satırdan sonra okumayı bırakırsa, bu okumuş olması gereken satırdır. Son tarih bir sunset ise, girdi bir deprecation bildirimi gibi okunmalıdır.
2. İsteyecekleri yeni şeyler. Her paragrafa bir tane, sonuç ilk cümlede.
3. İyileşen şeyler. Bildirilen hatalar, yükseltilen sınırlar, yavaş olan şeyler.
4. Diğer her şey, liste olarak. Bağımlılık güncellemeleri, dahili refactor’lar, küçük metin değişiklikleri. Her biri bir satır. Bu bölümü kimse okumaz, ve yine de orada olmalı, çünkü onu arayan kişi gerçekten ihtiyaç duyar.

Yeniden yazım

Önce:

v4.2.0 POST /exports endpoint’inin yük altında ara sıra 500 döndürdüğü sorun düzeltildi. Export worker’ı refactor edildi. node-pg 8.11’e güncellendi. CSV serializer’daki hata yönetimi iyileştirildi.

Sonra:

Exportlar artık büyük hesaplarda başarısız olmuyor. Yaklaşık 50.000 satırdan fazla olan hesaplar, ay sonuna doğru daha sık olmak üzere, bir export başlatırken 500 alabiliyordu. Bu düzeltildi, ve artık her boyuttaki export başarısız olmak yerine kendini yeniden dener. Hiçbir işlem gerekmiyor, ve geçen hafta başarısız olan herhangi bir export basitçe yeniden çalıştırılabilir.

4.2.0’da ayrıca: node-pg 8.11, CSV serializer’da daha net hatalar.

Aynı sürüm. İkincisi etkilenen hesabı, en kötü olduğu zamanı, neyin değiştiğini ve ne yapılacağını belirtiyor. Bağımlılık güncellemesi kaybolmadı, sadece başlık olmaktan çıktı. Release notes en iyi uygulamaları makalesi bu yeniden yazımın izlediği kuralların geri kalanına sahip, her birinin atlanma maliyetiyle birlikte.

Silinmeye değer şeyler

• “Duyurmaktan heyecan duyuyoruz.” Okuyucu henüz heyecanlı değil. Bunu bir sonraki cümlede kazanın.
• Dahili ticket numaraları. PROJ-4471 sizin tracker’ınızın dışında hiçbir anlam ifade etmez. Girdinin bir referansa ihtiyacı varsa, doküman sayfasına link verin.
• Sadece ekibinizin kullandığı bileşen adları. “Ingest pipeline”ı yeniden adlandırdıysanız, “import’lar” deyin.
• Tek başlık olarak bir sürüm numarası. v4.2.0 bir arşivleme etiketidir, özet değil.
• Kimsenin ziyaret etmediği bir ayarlar sayfasının ekran görüntüleri. Değişen şeyi kullanımda gösterin.

Release notes ne sıklıkla yayımlanmalı?

Bir şeyler olduğunda yayımlayın, bir programa göre değil. Her sürümde gelen notlar herkese onları görmezden gelmeyi öğretir. Bir şeyler olduğunda gelen notlar açılır. Hiç notu olmayan bir sürüm yayımlamak ve girdilerini okunmaya değer bir başlığa sahip bir sonraki sete devretmek uygun, ve genellikle doğrudur.

Changelog her şeyi kaydetmeye devam eder. İş bölümü budur: changelog eksiksizdir, notlar seçicidir. Changelog’u ilerledikçe yapılandırılmış tutarsanız, notları yazmak arkeoloji yerine seçim ve yeniden yazım olur.

Release notes şablonu seçim adımı için kullandığımız formdur, ve changelog örnekleri changelog’u notlar türetmek için yeterince iyi olan ekiplerin girdilerini toplar.

Bunların hepsi tamamen kontrol ettiğin, uzunluk sınırı olmayan ve çalışan linklere sahip bir sayfayı varsayar. Mobil uygulamalar için release notes yüzey bir App Store ya da Play Store girdisi olduğunda neyin değiştiğini ele alır. Acil durum release notes diğer istisnayı ele alır: normal yazım sürecini takip etmek için hiç zaman kalmadığında neyin değiştiğini.

Yayımlamadan önce bir test

Notları iki hafta tatilde olmuş ve 40 saniyesi olan biri gibi okuyun. O sürede kendisinden bir şey istenip istenmediğini anlayamıyorsa, notlar ne kadar doğru olursa olsun bitmemiş demektir.

FAQ

Release notes ne kadar uzun olmalı? Sonuç doğuran değişikliklerin gerektirdiği kadar, bir satır fazlası değil. Bir breaking change ve iki iyileştirme içeren bir sürüm üç paragraftır. Sessiz bir sürümü önemli göstermek için doldurmak, okuyucuların notları atlamayı öğrenmesinin yoludur.

Release notes’u kim yazmalı? Değişikliği anlayan kişi, onu anlamayan biri tarafından düzenlensin. Mühendis neyin değiştiğini bilir; editör bir yabancının neyi yanlış anlayacağını bilir. Girdiyi merge anında, mühendis henüz hatırlıyorken yazmak, bunu ucuza getiren pratiktir.

Release notes hata düzeltmelerini içermeli mi? Evet, birinin bildirdiği veya karşılaştığı olanları. Sebep değil, okuyucunun gördüğü belirtiyi belirtin. “50.000 satırdan fazla exportlar başarısız oluyordu” bir okuyucunun tanıdığı bir düzeltmedir; “export worker’daki race condition düzeltildi” bir commit mesajıdır.

Release notes ile changelog arasındaki fark nedir? Changelog eksiksiz, sürekli kayıttır; release notes bir sürüm hakkındaki, henüz ilgilenip ilgilenmeyeceğine karar vermemiş insanlar için yazılmış özenle seçilmiş mesajdır. Daha uzun cevap changelog vs release notes içindedir.

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

changeloop'ta ilgili sayfalar: Release notu şablonu, Changelog örnekleri