Acil durum release notes: zaman baskısı altında yazmak

Çoğu release notes, kod bittikten sonra rahatça gözden geçirilerek ve kimsenin onları ne kadar aciliyetle okuması gerektiğiyle hiçbir ilgisi olmayan bir programa göre yayımlanarak yazılır. Bir acil durum sürümü, bir güvenlik yaması, bir veri kaybı hatası, bir kesinti düzeltmesi, bu koşulların her birini aynı anda tersine çevirir: notlar, çoğu insanın normalde yazmaya başlayacağı zamandan önce var olmalı, neredeyse hiç inceleme almaz, ve rahat değil endişeli insanlar tarafından okunur. Release notes nasıl yazılır normal süreci ele alır; bu, onu takip etmek için zaman kalmadığında neyin değiştiğiyle ilgilidir.

Başka hiçbir şeyi doğru yapmasa da bir acil durum release notu’nun mutlaka doğru yapması gereken tek şey nedir?

Okuyucunun bir şey yapması gerekip gerekmediği, öncesinde hiçbir çerçeveleme olmadan ilk cümlede söylenmiş. Olay kaynaklı bir release notuna rastlayan bir okuyucu, sorunu bir durum sayfasından, bir destek konusundan, veya kendi kullanıcılarından duyduğu için genellikle zaten endişelidir, ve eylem maddesinden önce bağlamla açılan bir not, tam olarak alıkoymanın en kötü okunduğu koşullarda bilgiyi alıkoyma gibi okunur. “Hiçbir işlem gerekmiyor, bu, sömürmek için kullanıcı verisi gerektirmeyen bir güvenlik açığını yamalar” ve “Hemen güncelleyin: bu sürüm bir hesabın verilerini başka birine gösterebilecek bir hatayı düzeltir” ikisi de tek bir cümledir, ve ikisi de panik içindeki bir okuyucunun başka bir şey okumadan önce ihtiyaç duyduğu tüm işi yapar.

Buna zaman kalmadığında olağan düzenleme geçişi hâlâ geçerli mi?

Sıkıştırma içgüdüsü, onu normalde üreten çoklu taslak süreci böyle olmasa bile hayatta kalır. Yeniden yazım, ayrıntılı bir ilk taslağı temel cümlesine indirmeyi tarif eder; zaman baskısı altında genellikle kesecek bir ilk taslak yoktur, ki bu disiplinin sonrasında ayrı bir geçiş olarak değil, siz yazarken kafanızda çalışması gerektiği anlamına gelir. Buna yaklaşmanın en hızlı yolu: “bilmem gereken ne” diye soran birine yüksek sesle söyleyeceğiniz cümleyi yazın, sonra durun, çünkü o cümle genellikle hem üretilmesi en hızlı hem de o durumdaki bir okuyucunun gerçekten işleyeceği tek cümledir.

Soruna neyin sebep olduğundan tam emin olmadan önce bir not yayımlamak hiç uygun mudur?

Evet, not sahip olmadığınız bir güveni ima etmek yerine o belirsizlik konusunda dürüstse. “Ödeme sayfasında yükselen hata oranları için bir düzeltme dağıttık; hâlâ kök nedeni doğruluyoruz ve bu notu güncelleyeceğiz” savunulabilir ve doğru şekilde zaman kazandırır; gerçekte doğrulamadığınız belirli bir nedeni belirten bir not, yanlış çıkarsa insanların size sonradan karşı gösterdiği türden bir tahmin haline gelir. Burada önemli olan disiplin teşhis hızı değildir, notun güveninin ekibin gerçek güveninden hiçbir zaman fazla olmamasıdır, çünkü acil durum notundaki yanlış bir teknik iddia, kabul edilmiş bir bilinmezden güvene daha fazla zarar verir.

Fazla emin, doğrulanmamış:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Zaman baskısı altında dürüst:
"Düzeltildi: bazı müşterilere tek bir sipariş için iki
kez ücret yansıtıldı. Yeni oluşumları durdurduk ve
etkilenen hesapları 24 saat içinde iade ediyoruz. Kök
neden araştırılıyor."

Bir acil durum notu soruna neyin sebep olduğunu mu, yoksa sadece düzeltildiğini mi söylemeli?

Neyin düzeltildiğini ve okuyucunun ne yapması gerektiğini söyleyin; kök nedeni tahmin edilmiş değil gerçekten bilinene kadar bir takip için saklayın. Bir olayın ortasındaki bir okuyucu tam olarak iki gerçek ister, bu çözüldü mü ve beni etkiliyor mu, ve doğru olsa bile bir kök neden açıklaması, onu kaybetmenin en kötü olası anında bu iki gerçekle dikkat için rekabet eder. İnceleme bittikten sonra ayrı yayımlanan post-mortem, kök nedenin ait olduğu yerdir; iki belgeyi zaman baskısı altında karıştırmak, yazması daha yavaş ve okuması daha yavaş bir not üretir, bir acil durumun ihtiyaç duyduğunun tam tersi.

Mobil uygulamalardaki zorunlu güncelleme sorunu burada da geçerli mi?

Aynı ilke, daha da sıkıştırılmış. Mobil uygulamalar için release notes, notun her şeyden önce nedeni ve son tarihi belirtmesi gerektiği zorunlu güncellemeleri ele alır, çünkü okuyucu zaten seçeneği olmadığı için sinirlenmiştir; acil durum web release notu genellikle okuyucu için, ona göre hareket edip etmeyeceğini seçtiği anlamda opt-in’dir, ama aynı “önce kısıtlamayı belirt” içgüdüsü uygulanır, sadece farklı bir sebeple: sinirlenme değil, aciliyet.

Öyle olmaması gerekirken bir acil durum notunun bir suç kabulü gibi okunması nasıl önlenir?

Düzeltmeyi ve etkisini tarif edin, suçu değil, ve aşırı özür dileme dürtüsüne direnin, ki bu yukarıdaki iki gerçeği isteyen bir okuyucu için dolgu gibi okunur. “Bazı export’ları etkileyen bir hata bulduk ve düzelttik”, olana drama yüklemeden ne olduğunu söyler; “Değerli müşterilerimizi etkileyen bu ciddi sorun için son derece üzgünüz”, okuyucunun istemediği duygusal bir anı sunmak için yararlı bilgiyi tam bir cümle geciktirir. Kısa, gerçeğe dayalı bir not soğuk değildir, gerçek baskı altında sabırsızlık olan, güvence ihtiyacı olmayan okuyucunun gerçek durumuna saygı duyar.

FAQ

Bir acil durum release notu aynı inceleme sürecinden mi geçmeli? Daha hafif bir tanesinden, hiçbirinden değil: notun kesinliği abartmadığını kontrol eden tek bir hızlı incelemeci, maliyeti birkaç dakikaya değer, çünkü incelenmemiş bir teknik iddianın yanlış olma riski tam olarak hızlı yazıldığı için daha yüksektir.

Daha fazla detaya bağlantısı olmadan bir acil durum notu yayımlamak sorun mu? Sadece kısa süreliğine. Bağlantısız bir not yayımlanan ilk şey olarak işe yarar; ikisinden biri var olur olmaz bir durum sayfasına veya takibe bir tane ekleyin, çünkü size verdiğiniz tek cümleden fazlasını isteyen bir okuyucunun gidecek bir yere ihtiyacı vardır, orası “daha fazla detay yakında” dese bile.

Bir acil durum notu hiç tamamen atlanıp düzeltmenin sessizce yayınlanmasına izin verilmeli mi? Sadece hiçbir okuyucunun fark edemeyeceği veya etkilenemeyeceği sorunlar için; bir okuyucunun sorunu yaşamış olma ihtimali varsa, not ona bittiğini söyleyen şeydir, ve sessizlik sorunun hâlâ aktif olabileceği gibi okunur.

Bir acil durum notu olay çözüldükten sonra ne kadar süre sabitlenmiş veya belirgin kalmalı? Acil kaygı penceresi kapanana kadar, tipik olarak bir veya iki gün, sonra başka herhangi bir kayıt gibi normal changelog’a katlanabilir; haftalarca sabitlenmiş kalan bir not, çözülmüş yerine çözülmemiş bir endişe gibi okunmaya başlar.

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