Dari RFC ke ADR: Mencapai Keputusan dan Menjaga Pemikiran

Keputusan yang tidak dapat direkonstruksi oleh sesiapa pun

Pemimpin teknologi baru mengajukan soalan yang munasabah: mengapa setiap perkhidmatan berkomunikasi dengan sistem pengebilan melalui barisan itu? Terdapat satu ADR — ADR-014, empat ayat, ditulis sebelas bulan yang lalu. Konteks: "kami memerlukan integrasi pengebilan yang boleh dipercayai." Keputusan: "gunakan barisan." Akibat: "beberapa kelewatan tambahan." Ia secara teknikal adalah satu rekod. Ia tidak menjawab apa-apa.

Anda berada di sana, jadi anda tahu apa yang tidak dikatakan oleh ADR-014: perdebatan selama tiga minggu di dua saluran Slack dan satu thread PR yang hangat; pilihan API-synchronous yang kalah kerana had kadar yang telah dinaikkan sejak itu; bantahan jurutera kakitangan yang dijawab dengan satu penanda aras yang kini tidak dapat ditemui. Perdebatan itu berlaku. Rekod ditulis selepas itu, dari ingatan, oleh seorang individu, pada hari Jumaat.

Ini adalah mod kegagalan yang didokumentasikan dan hampir universal bagi amalan yang benar-benar baik. Panduan preskriptif AWS dan dokumen Well-Architected Microsoft kedua-duanya mengesyorkan ADR — dan kedua-duanya mencatat kesakitan: mengekalkan mereka terkini memerlukan masa, dan mengurusnya menjadi kompleks apabila pasukan dan pilihan bertambah. Punca utama adalah struktur: perdebatan dan rekod hidup di tempat yang berbeza, jadi rekod sentiasa merupakan transkripsi yang kehilangan makna. Penyelesaiannya adalah untuk menjadikannya di tempat yang sama. Amalan ini juga bukan khusus untuk kejuruteraan, atau bahkan khusus untuk ADR. Google memerlukan dokumen reka bentuk — masalah, pendekatan yang dicadangkan, alternatif yang dipertimbangkan, pertukaran — ditulis dan disemak sebelum kerja teknikal yang signifikan bermula, satu amalan yang dinyatakan dalam Software Engineering at Google syarikat itu sendiri. Ia adalah disiplin yang sama seperti ADR, diterapkan satu langkah lebih awal: ADR merekod pilihan yang dibentangkan oleh dokumen reka bentuk. Kedua-duanya gagal dengan cara yang sama untuk sebab yang sama, dan kedua-duanya diperbaiki dengan langkah yang sama — pegang perdebatan di mana rekod berada, bukannya mentranskripsikan satu ke dalam yang lain selepas itu. Baca setiap langkah di bawah sebagai merangkumi kedua-dua artefak.

Mengapa ADR menjadi rosak

Satu ayat dari bahan komuniti ADR sendiri membawa keseluruhan diagnosis: RFC biasanya berkaitan dengan mencapai persetujuan; ADR merekodkan persetujuan setelah dicapai. Dua artefak, dua momen — dan segala-galanya di antara mereka bocor. Alternatif yang "jelas" salah tidak direkodkan (sehingga mereka berhenti menjadi jelas). Bantahan yang membentuk reka bentuk akhir hanya tinggal sebagai komen PR pada thread yang ditutup. Bahagian konteks ditulis terakhir, paling teruk, oleh sesiapa yang kalah dalam permainan tidak-itu. Mesyuarat yang sepatutnya menghasilkan keputusan menghasilkan ringkasan sebaliknya, dan alasan yang menjadikan keputusan tahan lama — perkara yang bergantung kepada keseluruhan rantai kualiti keputusan — adalah tepat apa yang ditinggalkan oleh transkripsi.

Langkah 1–3: Cadangan, konteks, pilihan

1. 1Nyatakan cadangan sebagai tuntutan utama — keputusan yang dicadangkan, bukan soalan: "Kami akan mengarahkan semua penulisan bil melalui antrian yang tahan lama." Ayat ini adalah tajuk ADR masa depan. Titik semakan: akar wujud, satu ayat, ditulis oleh pencadang.
2. 2Konteks sebagai hujah pro yang berasingan. Setiap kekuatan yang menjadikan keputusan itu perlu — keperluan kebolehpercayaan, had kadar sistem pengebilan, mandat audit — adalah hujahnya sendiri di bawah akar. Perenggan "Konteks" yang monolitik tidak boleh dicabar; tiga tuntutan konteks yang berasingan boleh dipersoalkan, disahkan, atau ditolak secara individu. Checkpoint: ≥2 hujah konteks, setiap satu kekuatan.
3. 3Setiap pilihan mempunyai nodenya sendiri. Barisan, API segerak, pekerjaan kumpulan — argumen saudara, masing-masing dengan kelebihan dan kekurangan sendiri. Kelebihan/kekurangan adalah relatif kepada ibu bapa, jadi kelemahan pilihan tergantung pada pilihan itu, bukan pada keputusan. Sertakan pilihan yang anda jangkakan untuk ditolak: saudara yang ditolak adalah apa yang menjawab "kenapa kita tidak hanya…". Titik pemeriksaan: setiap pilihan yang mungkin ditanya oleh pembaca wujud.

Langkah 4–6: Pusingan RFC yang meninggalkan rekod

Kini pusingan ulasan — biasanya bahagian yang tersebar di sekitar perbualan, komen dan lorong. Di sini ia dijalankan sebagai tiga jenis pertukaran terstruktur, masing-masing merupakan dialog empat pusingan antara penilai dan pengarang pilihan:

Langkah 7: Memutuskan — dan apa yang bukan penilaian

Pengambil keputusan menilai pilihan: satu yang dilabelkan dengan penilaian masing-masing. Pengagihan adalah bukti yang sah — di mana bilik itu berdiri, dalam rekod, sebelum panggilan. Tetapi penilaian bukanlah keputusan. Seorang manusia yang dinamakan masih membuat keputusan, dan jika panggilan bertentangan dengan pengagihan, nod keputusan adalah di mana itu dijelaskan. (Siapa manusia yang dinamakan itu, dan bagaimana untuk menetapkan peranan sebelum perdebatan dan bukannya selepas, adalah disiplin tersendiri — lihat tutorial hak keputusan.)

Langkah 8–9: ADR yang anda tidak perlu tulis

Inilah hasilnya. Rekod ini bukan dokumen yang anda tulis selepas itu — ia adalah nod pilihan yang dipilih ditambah dengan segala yang sudah dilampirkan padanya: hujah konteks (Konteks), saudara yang ditolak (Pilihan Dipertimbangkan), rantai yang lengkap (perbincangan, dengan pengarang), penilaian (di mana kedudukan bilik), dan hujah keputusan dengan rasionalnya (Keputusan). Tiada yang ditranskripsikan, jadi tiada yang hilang dalam transkripsi.

1. 1Rekodkan akibat yang anda terima. Kelemahan yang diketahui — latensi tambahan, beban operasi barisan — terus wujud sebagai anak-anak yang tidak diingini dari pilihan yang dipilih, diakui oleh pengambil keputusan. Menuliskannya adalah apa yang menjadikannya sebagai keputusan dan bukannya pilihan. Checkpoint: ≥1 akibat yang diterima dalam rekod.
2. 2Eksport jika organisasi anda memerlukan ADR yang dijejaki repositori. Banyak yang memerlukan, dengan betul — ADR markdown di sebelah kod kekal sebagai artefak pematuhan. Tulis ringkasan empat bahagian dari pokok (lima minit, bukan hari Jumaat), pautkan kembali kepada perbincangan untuk perdebatan penuh. Checkpoint: ADR repositori merujuk kepada pokok; pokok menyimpan alasan.

Bersetuju untuk tidak bersetuju, secara rasmi

Corak yang terkenal oleh Amazon — tidak setuju dan komited — mempunyai masalah kebolehan dibaca: bagaimana seseorang tahu kemudian bahawa ketidaksetujuan itu adalah nyata, didengar, dan dijawab, dan bukannya dipaksa? Mekanik rantai menjawabnya. Rantai Ulasan yang menjalani empat pusingan penuh dan diselesaikan tanpa persetujuan adalah tepat resitnya: bantahan telah dibuat, dijawab, ditekan, dan dijawab semula, secara rasmi, sebelum penentang berkomitmen. Penentang didokumenkan sebagai telah didengar — yang menjadikan komitmen selepas itu munasabah dan bukannya sekadar patuh.

Langkah 10: Menggantikan tanpa memadam

Keputusan berumur. Apabila had kadar yang membunuh pilihan segerak dinaikkan, langkah yang betul adalah keputusan baru yang merujuk kepada yang digantikannya — satu hujah baru yang berkaitan dengan nod ADR-014, menyatakan apa yang telah berubah. Keputusan lama tetap boleh dibaca; alasannya adalah tepat mengapa keputusan baru tahu apa yang sedang dibatalkannya.

Satu jurang yang jujur untuk diurus secara eksplisit: tiada medan status ADR terbina dalam. Dicadangkan / diterima / digantikan bukanlah keadaan kelas pertama dalam satu hujah — penggantian dimodelkan dengan menghubungkan, dan konvensyen itu adalah tanggungjawab anda untuk dikekalkan. Nyatakan dalam perjanjian kerja pasukan anda daripada menganggap produk menguatkuasakannya.

Had yang jujur

• ✗Ini tidak menggantikan ADR dalam repositori anda jika organisasi anda memerlukan mereka dikawal versi bersebelahan dengan kod. Eksport dan komit ringkasan; gunakan pokok untuk bahagian yang markdown tidak baik — perdebatan.
• ✗Tidak ada medan status ADR. Dicadangkan/diterima/digantikan adalah konvensyen penghubung yang anda kekalkan, bukan sesuatu yang dikuatkuasakan oleh produk.
• ✗Rantaian adalah empat pusingan. Perbezaan pendapat yang mendalam dalam seni bina akan memerlukan panggilan; rantaian adalah rekod tentang apa yang telah dicuba sebelum ini.
• ✗Penilaian adalah nilai berlabel tunggal, bukan penilaian berbilang kriteria yang diberi berat.
• ✗Ia tidak membuat sesiapa menulis konteks yang baik. Struktur mengurangkan kos rekod yang baik; ia tidak memberikan penilaian.

Pelajaran praktikal

• ✓Satu RFC, satu perbincangan. Tahan daripada mega-pokok yang menutupi keseluruhan seni bina suku — pautan supersession menghubungkan keputusan dengan lebih baik daripada pengnestingan.
• ✓Benih dari apa yang ada. Transkrip yang penuh dengan keputusan atau folder ADR lama anda, yang diekstrak, memberikan perdebatan permulaan yang baik — dilabel sebagai diimport, supaya hujah langsung tetap dapat dibezakan.
• ✓Letakkan nama pengulas pada rantai mereka dan biarkan di situ. Pemberian atribusi adalah tanggungjawab; bantahan seni bina yang tanpa nama akan menjadi folklore.
• ✓Bahagian akibat adalah milik penentu, bukan orang lain. Kelemahan yang diterima yang ditulis oleh orang yang menerimanya mempunyai berat yang berbeza daripada amaran penilai.

ADR-014, versi yang menjawab

Kembali kepada soalan pemimpin teknologi yang baru. Dalam versi yang dibina semula, ADR-014 adalah satu nod: keputusan antrian dengan rasionalnya, tiga kekuatan konteks (satu kini sudah lapuk — jelas), seorang saudara API segerak yang ditolak yang nama fatalnya menyebut had kadar lama, empat rangkaian Semakan yang telah diselesaikan termasuk milik jurutera kakitangan, dan penanda aras yang dilampirkan sebagai bukti. Pemimpin teknologi membaca selama sepuluh minit, melihat had kadar telah diubah, dan membuka cadangan yang menggantikan yang dipautkan kepada nod lama. Tiada siapa yang menggali Slack. Itulah keseluruhan janji: rangkaian mencapai persetujuan, pokok merekodnya — dan rekod itu menjawab soalan yang anda tidak tahu ia akan ditanya.