Release notes darurat: menulis di bawah tekanan waktu nyata

Kebanyakan release notes ditulis setelah kode selesai, ditinjau dengan santai, dan diterbitkan sesuai jadwal yang tidak ada hubungannya dengan seberapa mendesak seseorang perlu membacanya. Rilis darurat, patch keamanan, bug kehilangan data, perbaikan gangguan, membalikkan semua kondisi itu sekaligus: catatan harus ada sebelum kebanyakan orang biasanya akan mulai menulisnya, hampir tidak mendapat tinjauan, dan dibaca orang yang cemas alih-alih santai. Cara menulis release notes membahas proses normal; ini tentang apa yang berubah saat tidak ada waktu tersisa untuk mengikutinya.

Apa satu hal yang harus benar dilakukan catatan rilis darurat jika tidak ada hal lain?

Apakah pembaca perlu melakukan sesuatu, dinyatakan di kalimat pertama, tanpa framing apa pun sebelumnya. Pembaca yang menemukan catatan rilis yang dipicu insiden sering kali sudah khawatir, karena mendengar tentang masalah dari halaman status, thread dukungan, atau penggunanya sendiri, dan catatan yang dibuka dengan konteks sebelum item tindakan terbaca sebagai menahan informasi tepat dalam keadaan di mana menahan terbaca paling buruk. “Tidak perlu tindakan, ini menambal kerentanan yang tidak memerlukan data pengguna untuk dieksploitasi” dan “Perbarui segera: rilis ini memperbaiki bug yang bisa menampilkan data satu akun ke akun lain” keduanya satu kalimat, dan keduanya melakukan seluruh pekerjaan yang dibutuhkan pembaca yang panik sebelum membaca hal lain apa pun.

Apakah pengeditan biasa masih berlaku saat tidak ada waktu untuk melakukannya?

Naluri untuk memampatkan bertahan bahkan saat proses banyak draf yang biasanya menghasilkannya tidak bertahan. Penulisan ulang menjelaskan memangkas draf pertama yang bertele-tele menjadi kalimat esensialnya; di bawah tekanan waktu sering kali tidak ada draf pertama untuk dipangkas, yang berarti disiplinnya harus berjalan di kepala Anda saat menulis alih-alih sebagai langkah terpisah setelahnya. Cara tercepat untuk mendekatinya: tulis kalimat yang akan Anda katakan dengan lantang kepada seseorang yang bertanya “apa yang perlu saya ketahui”, lalu berhenti, karena kalimat itu biasanya baik yang tercepat diproduksi maupun satu-satunya yang benar-benar akan diproses pembaca dalam keadaan itu.

Apakah pernah tidak apa-apa menerbitkan catatan sebelum benar-benar yakin apa penyebab masalahnya?

Ya, jika catatannya jujur tentang ketidakpastian itu alih-alih menyiratkan keyakinan yang tidak Anda miliki. “Kami telah menyebarkan perbaikan untuk tingkat error yang meningkat di checkout; kami masih mengonfirmasi akar penyebabnya dan akan memperbarui catatan ini” bisa dipertahankan dan membeli waktu dengan benar; catatan yang menyatakan penyebab spesifik yang sebenarnya belum Anda konfirmasi adalah jenis tebakan yang menjadi hal yang dikutip kembali orang kepada Anda nanti jika ternyata salah. Disiplin yang penting di sini bukan kecepatan diagnosis, tapi tidak pernah membiarkan keyakinan catatan melebihi keyakinan tim yang sebenarnya, karena klaim teknis yang salah dalam catatan darurat merusak kepercayaan lebih daripada ketidaktahuan yang diakui.

Terlalu yakin, belum diverifikasi:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Jujur di bawah tekanan waktu:
"Diperbaiki: beberapa pelanggan dikenakan biaya dua kali
untuk satu pesanan. Kami telah menghentikan kejadian baru
dan mengembalikan dana akun yang terdampak dalam 24 jam.
Menyelidiki akar penyebab."

Apakah catatan darurat harus menyebutkan penyebab masalahnya, atau hanya bahwa itu sudah diperbaiki?

Katakan apa yang diperbaiki dan apa yang harus dilakukan pembaca; simpan akar penyebab untuk tindak lanjut begitu benar-benar diketahui, bukan diperkirakan. Pembaca di tengah insiden ingin tepat dua fakta, apakah ini sudah teratasi dan apakah ini memengaruhi saya, dan penjelasan akar penyebab, bahkan yang akurat, bersaing dengan dua fakta itu untuk perhatian pada momen terburuk untuk kehilangannya. Postmortem, diterbitkan terpisah begitu investigasi selesai, adalah tempat akar penyebab seharusnya berada; mencampur kedua dokumen di bawah tekanan waktu menghasilkan catatan yang lebih lambat ditulis dan lebih lambat dibaca, kebalikan dari yang dibutuhkan keadaan darurat.

Apakah masalah pembaruan paksa dari aplikasi mobile juga berlaku di sini?

Prinsip yang sama, lebih dipampatkan lagi. Release notes untuk aplikasi mobile membahas pembaruan paksa, di mana catatan harus menyatakan alasan dan tenggat waktu sebelum apa pun karena pembaca sudah kesal karena tidak punya pilihan; release note darurat web biasanya opt-in bagi pembaca dalam artian mereka memilih apakah akan bertindak berdasarkan itu, tapi naluri “nyatakan batasan lebih dulu” yang sama berlaku, hanya karena alasan berbeda: bukan kekesalan, kemendesakan.

Bagaimana menghindari catatan darurat terbaca sebagai pengakuan kesalahan padahal seharusnya tidak?

Jelaskan perbaikannya dan efeknya, bukan kesalahannya, dan tahan dorongan untuk meminta maaf berlebihan, yang terbaca sebagai pengisi bagi pembaca yang menginginkan dua fakta di atas. “Kami menemukan dan memperbaiki bug yang memengaruhi beberapa ekspor” menyatakan apa yang terjadi tanpa menambahkan drama padanya; “Kami sangat menyesal atas masalah serius ini yang berdampak pada pelanggan kami yang berharga” menunda informasi yang berguna satu kalimat penuh untuk menyampaikan momen emosional yang tidak diminta pembaca. Catatan yang singkat dan faktual tidak dingin, itu menghormati keadaan pembaca yang sebenarnya, yang di bawah tekanan nyata adalah ketidaksabaran, bukan kebutuhan akan ketenangan.

FAQ

Haruskah release note darurat melalui proses tinjauan yang sama dengan yang normal? Yang lebih ringan, bukan tanpa sama sekali: satu peninjau cepat yang memeriksa bahwa catatan tidak melebih-lebihkan kepastian sepadan dengan beberapa menit yang dibutuhkannya, karena risiko klaim teknis yang tidak ditinjau menjadi salah lebih tinggi justru karena ditulis dengan cepat.

Apakah tidak apa-apa menerbitkan catatan darurat tanpa tautan ke detail lebih lanjut? Hanya sebentar. Catatan tanpa tautan berfungsi sebagai hal pertama yang diterbitkan; tambahkan satu ke halaman status atau tindak lanjut begitu salah satunya ada, karena pembaca yang menginginkan lebih dari satu kalimat yang Anda berikan butuh tempat untuk pergi, meskipun tempat itu mengatakan “detail lebih lanjut segera”.

Haruskah catatan darurat pernah dilewati sepenuhnya, membiarkan perbaikan dirilis secara diam-diam? Hanya untuk masalah yang tidak bisa disadari atau terdampak oleh pembaca mana pun; jika ada kemungkinan pembaca mengalami masalahnya, catatan adalah yang memberi tahu mereka bahwa itu sudah berakhir, dan keheningan terbaca seolah masalahnya mungkin masih aktif.

Berapa lama catatan darurat harus tetap disematkan atau menonjol setelah insiden teratasi? Sampai jendela kecemasan langsung menutup, biasanya satu atau dua hari, lalu bisa melipat ke dalam changelog normal seperti entri lainnya; catatan yang tetap disematkan selama berminggu-minggu mulai terbaca sebagai kekhawatiran yang belum teratasi alih-alih yang sudah teratasi.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Templat catatan rilis, Contoh changelog