Cara menulis release notes yang benar-benar dibaca orang

Untuk menulis release notes yang dibaca orang, jawab satu pertanyaan per entri: apa yang bisa dilakukan pembaca sekarang yang sebelumnya tidak bisa, dan apa yang harus mereka lakukan. Letakkan apa pun yang punya tenggat waktu di paling atas, sebutkan siapa yang terdampak, katakan “tidak ada tindakan yang diperlukan” jika itu benar, dan lewati rilis yang tidak punya apa-apa untuk disampaikan. Semua hal lain di halaman ini adalah penerapan aturan itu.

Perbaikan bug dan peningkatan performa.

Setiap produk pernah merilis ini. Penyebabnya jarang kemalasan: ini yang terjadi ketika release notes ditulis dari dalam, oleh seseorang yang sudah dua minggu tenggelam dalam diff dan tidak bisa lagi melihat bagian mana yang akan dipedulikan orang luar. Gaya bahasa yang lebih baik tidak akan memperbaikinya; menjawab pertanyaannya yang akan.

Apa yang harus dicakup release notes?

Release notes harus mencakup, untuk setiap perubahan yang layak disebut: apa yang bisa dilakukan pembaca sekarang, siapa yang terdampak, apa yang harus mereka lakukan (termasuk “tidak ada”), dan kapan sesuatu yang punya tenggat waktu berlaku. Release notes tidak boleh mencakup nomor tiket internal, nama komponen yang hanya digunakan tim, atau nomor versi sebagai satu-satunya judul.

Pemisahan antara release note dan entri changelog adalah yang membuat daftar ini mungkin: changelog menyimpan semuanya, jadi catatan bisa melewatkan sesuatu. Contoh beranotasi untuk setiap jenis entri dikumpulkan di contoh release notes.

Pertanyaan yang dijawab setiap entri

Apa yang bisa dilakukan pembaca sekarang yang sebelumnya tidak bisa, dan apa yang harus mereka lakukan?

Jika sebuah entri tidak bisa menjawab itu, entri tersebut milik changelog, bukan release notes. Kedua bagian penting. Bagian pertama adalah nilai. Bagian kedua adalah yang dilupakan tim, dan itu yang menghasilkan tiket dukungan ketika hilang.

Dua contoh bagian kedua yang benar-benar bekerja:

• “Webhook yang ada tetap berfungsi hingga 1 November. Setelah itu, payload yang tidak ditandatangani akan ditolak.”
• “Tidak ada tindakan yang diperlukan. Ekspor yang ada akan dienkode ulang secara otomatis saat Anda membukanya lagi.”

Yang kedua secara eksplisit mengatakan “tidak ada tindakan yang diperlukan”. Kalimat itu layak ditulis setiap kali, karena pembaca yang tidak menemukannya akan mengasumsikan yang terburuk.

Bagaimana release notes harus diurutkan?

Urutkan berdasarkan konsekuensi bagi pembaca, jangan pernah berdasarkan bagian sistem yang berubah. Mengelompokkan berdasarkan API, dasbor, seluler dan infrastruktur adalah bagan organisasi Anda, bukan masalah pembaca.

1. Breaking change dan apa pun yang punya tenggat waktu. Selalu pertama, meski kecil. Jika pembaca berhenti membaca setelah satu baris, ini baris yang harus mereka baca. Jika tenggat waktunya adalah sunset, entri tersebut harus terdengar seperti pemberitahuan deprecation.
2. Apa yang baru dan akan mereka inginkan. Satu per paragraf, dengan hasil di klausa pertama.
3. Apa yang membaik. Bug yang dilaporkan, batas yang dinaikkan, hal-hal yang lambat.
4. Semua yang lain, sebagai daftar. Pembaruan dependensi, refactor internal, salinan kecil. Satu baris masing-masing. Tidak ada yang membaca bagian ini, dan tetap harus ada, karena orang yang mencarinya benar-benar membutuhkannya.

Penulisan ulang

Sebelum:

v4.2.0 Memperbaiki masalah di mana endpoint POST /exports sesekali mengembalikan 500 saat beban tinggi. Merefaktor worker ekspor. Memperbarui node-pg ke 8.11. Meningkatkan penanganan error di serializer CSV.

Sesudah:

Ekspor tidak lagi gagal pada akun besar. Akun dengan lebih dari sekitar 50.000 baris bisa mendapatkan 500 saat memulai ekspor, lebih sering di akhir bulan. Ini sudah diperbaiki, dan ekspor ukuran apa pun sekarang mencoba lagi sendiri alih-alih gagal. Tidak ada tindakan yang diperlukan, dan ekspor mana pun yang gagal minggu lalu bisa langsung dijalankan ulang.

Juga di 4.2.0: node-pg 8.11, error yang lebih jelas di serializer CSV.

Rilis yang sama. Yang kedua menyebutkan akun yang terdampak, saat kondisinya terburuk, apa yang berubah, dan apa yang harus dilakukan. Pembaruan dependensi tidak menghilang, hanya berhenti menjadi judul. Artikel praktik terbaik release notes punya sisa aturan yang diikuti penulisan ulang ini, masing-masing dengan biaya melewatkannya.

Hal-hal yang layak dihapus

• “Kami dengan senang hati mengumumkan.” Pembaca belum senang. Dapatkan itu di kalimat berikutnya.
• Nomor tiket internal. PROJ-4471 tidak berarti apa-apa di luar tracker Anda. Jika entri butuh referensi, tautkan ke halaman dokumen.
• Nama komponen yang hanya digunakan tim Anda. Jika Anda mengganti nama “pipeline ingest”, katakan “impor”.
• Nomor versi sebagai satu-satunya judul. v4.2.0 adalah label pengarsipan, bukan ringkasan.
• Screenshot halaman pengaturan yang tidak pernah dikunjungi siapa pun. Tunjukkan hal yang berubah, dalam penggunaan.

Seberapa sering release notes harus diterbitkan?

Terbitkan saat sesuatu terjadi, bukan sesuai jadwal. Catatan yang datang setiap rilis melatih semua orang untuk mengabaikannya. Catatan yang datang saat sesuatu terjadi dibuka. Tidak apa-apa, dan biasanya benar, untuk merilis tanpa catatan sama sekali dan menggulirkan entrinya ke set berikutnya yang punya judul yang layak dibaca.

Changelog tetap mencatat semuanya. Itulah pembagian kerjanya: changelog lengkap, catatannya selektif. Jika Anda menjaga changelog tetap terstruktur seiring waktu, menulis catatan menjadi seleksi dan penulisan ulang, bukan arkeologi.

Template release notes adalah bentuk yang kami gunakan untuk langkah seleksi, dan contoh changelog mengumpulkan entri dari tim yang changelog-nya cukup baik untuk diturunkan menjadi catatan.

Semua ini mengasumsikan halaman yang sepenuhnya Anda kendalikan, tanpa batas panjang dan dengan tautan yang berfungsi. Release notes untuk aplikasi mobile membahas apa yang berubah saat permukaannya adalah daftar App Store atau Play Store. Release notes darurat membahas pengecualian lainnya: apa yang berubah saat tidak ada waktu tersisa sama sekali untuk mengikuti proses penulisan normal.

Satu tes sebelum menerbitkan

Baca catatan seperti seseorang yang baru liburan dua minggu dan punya 40 detik. Jika, dalam waktu itu, mereka tidak bisa memastikan apakah ada yang diminta dari mereka, catatan tersebut belum selesai, seakurat apa pun catatan itu.

FAQ

Seberapa panjang release notes seharusnya? Sepanjang yang dibutuhkan perubahan berkonsekuensi, dan tidak lebih satu baris pun. Rilis dengan satu breaking change dan dua peningkatan adalah tiga paragraf. Mengisi rilis yang sepi agar terlihat substansial adalah cara pembaca belajar melewatkan catatan.

Siapa yang harus menulis release notes? Orang yang memahami perubahannya, diedit oleh seseorang yang tidak memahaminya. Insinyur tahu apa yang berubah; editor tahu apa yang akan salah dipahami orang luar. Menulis entri saat merge, selagi insinyur masih mengingatnya, adalah praktik yang membuat ini murah.

Apakah release notes harus mencakup perbaikan bug? Ya, yang dilaporkan atau dialami seseorang. Nyatakan gejala yang dilihat pembaca, bukan penyebabnya. “Ekspor lebih dari 50.000 baris gagal” adalah perbaikan yang dikenali pembaca; “memperbaiki race condition di worker ekspor” adalah pesan commit.

Apa perbedaan antara release notes dan changelog? Changelog adalah catatan lengkap dan berkelanjutan; release notes adalah pesan terkurasi tentang satu rilis, ditulis untuk orang yang belum memutuskan apakah mereka peduli. Jawaban yang lebih panjang ada di changelog vs release notes.

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