Cara membangun halaman changelog yang diikuti orang

Halaman changelog layak dibangun ketika seseorang akan kembali ke sana. Itu standar yang lebih tinggi daripada sekadar memilikinya, dan itulah standar yang paling sering gagal dipenuhi: halaman yang ada, ditautkan di footer, diperbarui secara sporadis, dan tidak dikunjungi siapa pun kecuali saat insiden. Keputusan yang memisahkan keduanya dibuat sebelum apa pun ditulis, dan sebagian besar tentang di mana halaman itu berada dan apa lagi yang dihasilkan dari konten yang sama.

Apa itu halaman changelog?

Ini adalah daftar publik dan bertanggal tentang apa yang berubah pada sebuah produk, di URL milik Anda. Ini salah satu dari lima permukaan tempat entri yang sama bisa muncul, dan pertanyaan yang berguna bukan mana yang dipilih, melainkan mana yang kanonik dan mana yang dihasilkan darinya.

Pilih satu sumber kanonik, terbitkan sekali, dan hasilkan sisanya. Tim yang memelihara halaman dan widget secara terpisah dengan tangan akan berakhir dengan dua teks yang tidak cocok, dan ketidakcocokan itu ditemukan oleh pelanggan.

Di mana sebaiknya halaman changelog berada?

Di domain Anda sendiri, di path yang stabil, dengan setiap entri dapat dialamatkan secara individual. Tiga lokasi umum adalah path di situs utama, subdomain, dan bagian dari dokumentasi. Path di situs utama adalah pilihan default yang seharusnya diperdebatkan penolakannya, bukan dukungannya: ia mewarisi otoritas situs, tidak butuh sertifikat atau DNS tambahan, dan menjaga halaman dalam navigasi yang sama dengan yang lain.

Subdomain adalah jawaban yang tepat ketika halaman dilayani oleh sistem yang berbeda dari situs marketing dan Anda kalau tidak akan melakukan proxy. Biayanya adalah ia mengumpulkan otoritas secara terpisah. Menempatkan changelog di docs itu tepat ketika audiensnya developer, dengan alasan yang dibahas di changelog API: pembaca biasanya sudah ada di sana.

Yang lebih penting daripada pilihan itu adalah entri harus bisa ditautkan secara individual. Orang menautkan entri dalam tinjauan insiden dan tiket internal, dan entri yang hanya bisa ditautkan sebagai “changelog, scroll ke bawah” akan ditempel sebagai screenshot sebagai gantinya.

Apa yang dibutuhkan halaman changelog?

Lima hal, dan pada dua yang pertama sebagian besar halaman gagal. Entri bertanggal per perubahan, yang terbaru dulu. Kategori atau label per entri agar bisa dipindai berdasarkan jenis yang diminati. Permalink per entri. Jalur berlangganan. Pencarian atau filter setelah sekitar lima puluh entri.

Selebihnya opsional. Screenshot membantu dan memakan biaya pemeliharaan. Nama penulis membangun kepercayaan di beberapa produk dan menjadi noise di produk lain. Nomor versi penting bagi pemanggil sebuah API dan hampir tidak ada orang lain. Keep a Changelog adalah pilihan default yang masuk akal untuk label jika Anda tidak punya alasan menciptakan sendiri, dan aturan intinya adalah yang layak dipertahankan bahkan jika Anda membuang sisanya: log ditulis untuk manusia.

Kelompokkan berdasarkan tanggal, bukan versi, ketika produk Anda merilis secara berkelanjutan. Pembaca yang memindai “apakah ini sebelum atau sesudah insiden kami tanggal sembilan” mencari tanggal, dan halaman yang diorganisasi berdasarkan nomor versi memaksanya menghitung.

Halaman atau widget in-app?

Keduanya, dari satu sumber. Halaman adalah tempat pencarian, tautan, dan catatan panjang berada. Widget adalah cara Anda menjangkau mayoritas pengguna yang tidak akan pernah mengunjungi halaman, dan ia berfungsi karena muncul di produk yang sudah mereka gunakan.

Kegagalan widget adalah gangguan. Badge yang menuntut perhatian untuk setiap entri akan diabaikan secara permanen dalam seminggu, yang membuat Anda kehilangan kanal untuk entri yang benar-benar penting. Hitung yang belum dibaca sejak terakhir kali pembaca melihat, semai penghitung secara diam pada kunjungan pertama agar tidak ada yang disambut badge riwayat satu tahun, dan biarkan pembaca membukanya sendiri alih-alih Anda membukanya untuk mereka.

Bagaimana membuat halaman changelog bisa dibaca mesin?

Terbitkan entri yang sama sebagai feed. Feed JSON adalah pilihan dengan gesekan paling rendah bagi apa pun yang mengonsumsinya lewat kode, dan feed RSS adalah yang diharapkan developer yang berlangganan di reader. Keduanya murah begitu entri menjadi data terstruktur alih-alih HTML yang ditulis tangan, yang merupakan alasan sebenarnya untuk menjaga salinan kanonik tetap terstruktur.

Beri markup pada halaman juga. Entri adalah karya dengan tanggal dan judul, dan schema.org menyediakan kosakatanya. Ini layak dilakukan dengan alasan yang sama seperti permalink: membuat halaman bisa digunakan oleh hal-hal yang bukan browser, termasuk proses rilis pelanggan sendiri. Tidak satu pun ini berfungsi jika entri yang mendasarinya tidak pernah menjadi data terstruktur sejak awal; format berkas changelog membahas berapa biaya masing- masing dari Markdown, JSON, dan YAML sebagai sumber kebenaran tempat feed dan markup ini sebenarnya dihasilkan.

Apakah halaman changelog membantu SEO?

Secara tidak langsung dan lambat. Entri individual jarang meranking, karena tidak menargetkan query apa pun yang diketik orang. Halaman mendapatkan tempatnya lewat tautan: entri dikutip dalam balasan support, forum, dan analisis insiden, dan tautan itu menumpuk di URL milik Anda. Halaman yang diperbarui setiap minggu selama dua tahun juga menjadi sinyal kesegaran yang kredibel bagi produk yang dimilikinya.

Yang tidak berhasil adalah memperlakukan entri sebagai content marketing. Entri yang digelembungkan menjadi tiga paragraf demi panjang lebih buruk dalam tugas sebenarnya, yaitu memberi tahu pembaca dalam satu kalimat apakah sesuatu yang mereka gunakan berubah. Jika Anda ingin changelog mendukung pencarian, tempatkan usaha pada permalink, feed, dan tautan internal ke sana, dan biarkan entri tetap singkat. Halaman contoh changelog kami sendiri mengumpulkan halaman yang menangkap keseimbangan ini dengan tepat.

Bagaimana orang berlangganan?

Berikan mereka jalur yang sudah mereka gunakan: feed RSS atau JSON untuk developer, email untuk yang hanya ingin mendengar hal penting, dan widget in-app untuk semua yang tidak akan pernah melakukan keduanya. Tanyakan apa yang ingin mereka dengar alih-alih mengasumsikannya, karena pembaca yang menginginkan breaking change dan menerima perbaikan teks akan berhenti berlangganan dari keduanya.

Jalur yang sebaiknya ditambahkan terakhir adalah yang menutup loop. Ketika sebuah entri menyelesaikan apa yang diminta seseorang secara spesifik, beri tahu mereka langsung alih-alih berharap mereka membaca halaman. Di changeloop, entri diterbitkan sekaligus di halaman, feed, dan widget, dan orang yang masukan widget-nya menjadi issue GitHub yang ditutup oleh pull request diberi tahu di issue itu dengan tautan ke entri, dan melihat entri tersebut di widget. Mekanismenya sama seperti langganan apa pun; bedanya, penerima sudah bertanya. Itulah argumen yang dijelaskan di menutup loop feedback dari sisi changelog.

FAQ

Sebaiknya halaman changelog di subdomain atau path? Secara default, path di situs utama, karena mewarisi otoritas situs dan tidak butuh infrastruktur tambahan. Subdomain dibenarkan ketika sistem berbeda melayani halaman itu.

Berapa banyak entri yang sebaiknya ditampilkan halaman sekaligus? Cukup untuk mengisi layar dan tidak lebih, dengan paginasi setelahnya. Memuat riwayat dua tahun ke satu dokumen itu lambat dan membuat entri terbaru lebih sulit ditemukan.

Apakah entri lama pernah perlu dihapus? Tidak. Entri dikutip dari luar situs Anda dan tautan akan rusak. Perbaiki entri di tempatnya dengan catatan, dan jaga URL tetap hidup.

Apakah setiap perubahan harus muncul di halaman? Hanya yang mungkin diperhatikan pengguna. Halaman yang mencatat refactor internal melatih pembaca untuk hanya melirik, dan halaman yang dilirik gagal pada hari ia membawa sesuatu yang mendesak.

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

Terkait di changeloop: Contoh changelog, Dokumentasi developer