Dokumen desain dianggap berbahaya – Beragampengetahuan

Di suatu tempat di Google Drive perusahaan Anda, terdapat dokumen desain dari enam bulan lalu. Ini menggambarkan sistem yang tidak ada. Ini menjadi usang pada sprint kedua dan ditinggalkan pada sprint ketiga. Empat belas orang mengomentari hal ini. Tidak ada yang memperbaruinya. Itu ada di sana, diformat dengan sempurna, menggambarkan alam semesta paralel tempat proyek berjalan sesuai rencana.

Kami pernah memberinya nama: Air Terjun. Kami menghabiskan waktu puluhan tahun untuk memberantasnya. Lalu kami memasukkannya ke dalam Google Doc dengan template yang lebih baik dan menyebutnya sebagai “praktik terbaik”.

Dalam artikel ini, saya akan menjelaskan mengapa dokumen desain ada, mengapa gagal, dan apa yang harus dilakukan untuk mengatasinya.

Mengapa dokumen desain ada?

Dokumen desain ada karena mereka membentuk organisasi Merasa lebih aman.

Saat sebuah tim menulis dokumen desain, janji tersiratnya adalah: “Kami telah memikirkan hal ini dengan hati-hati, sehingga akan berjalan sesuai rencana.” Janji ini menghibur para manajer, direktur, dan wakil presiden yang perlu melaporkan kemajuannya. Ini mengubah aktivitas yang pada dasarnya tidak dapat ditentukan (menulis perangkat lunak) menjadi Rasanya Persis seperti proses manufaktur yang dapat diprediksi.

Hal ini karena dokumen desain memberikan fungsi organisasi yang sama dengan fase persyaratan air terjun yang disediakan pada tahun 1970an: dokumen tersebut menciptakan artefak yang dapat ditinjau, disetujui, dan dikritik. Jika terjadi kesalahan pada suatu proyek, seseorang dapat menunjuk ke dokumen tersebut dan berkata, “Oke, desainnya disetujui,” sehingga mengalihkan kesalahan dari ketidakmampuan organisasi menangani ketidakpastian menjadi ketidakmampuan para insinyur dalam memprediksi masa depan.

Tidak percaya padaku? Tanyakan pada diri Anda berapa banyak dokumen desain perusahaan Anda yang telah diperbarui sejak implementasi dimulai. Jika dokumen ini memang berguna sebagai alat desain, Anda akan memperbaruinya sambil mempelajarinya. Tidak ada yang melakukan ini. Tugas dokumentasi tidak pernah memandu implementasi. Tugasnya adalah mendapatkan tanda tangan.

Mengapa Pra-Spesifikasi Terperinci Gagal

Masalah mendasar dengan dokumentasi desain adalah masalah yang sama yang mematikan air terjun: Anda memiliki informasi paling sedikit di awal proyek, dan inilah saat dokumen desain mengharuskan Anda membuat keputusan terbanyak.

Ini adalah keseluruhan dasar intelektual dari pengembangan berulang. Alasan kami berhenti menulis spesifikasi persyaratan sepanjang 200 halaman adalah karena kami telah belajar melalui pengalaman menyakitkan selama puluhan tahun bahwa Anda tidak sepenuhnya memahami suatu masalah sampai Anda mulai menyelesaikannya.

Menulis dokumen desain detail sebelum coding seperti menulis rencana perjalanan mendetail sebelum mengunjungi negara yang belum pernah Anda kunjungi. Anda berencana menghabiskan tiga jam di museum, tetapi museum tutup pada hari Selasa. Anda akan mengalokasikan satu hari ke kota-kota yang bernilai satu minggu. Anda akan kehilangan restoran terbaik di kota karena tidak ada dalam panduan perjalanan mana pun.

Rencana perjalanan tidak ada gunanya karena informasi yang Anda perlukan untuk merencanakan dengan baik sebelum Anda tiba tidak ada. Kualitas rencana apa pun bergantung pada apa yang Anda ketahui, dan ketika Anda memulai sesuatu yang baru, Anda hampir tidak tahu apa-apa.

Hal inilah yang terjadi pada dokumen desain. Sebelum memahami pola kueri, Anda perlu menentukan skema database. Sebelum Anda memahami panggilan mana yang benar-benar penting bagi kinerja, buatlah diagram API. Anda menghitung kasus tepi sebelum Anda melihat data sebenarnya. Kemudian Anda mulai membuat kode dan menemukan bahwa kenyataan tidak sesuai dengan dokumentasi Anda di setiap dimensi yang menarik.

Pada titik ini, salah satu dari dua hal terjadi. Entah Anda memperbarui dokumentasi (tidak ada yang memperbaruinya), atau Anda diam-diam menyimpang darinya. Tidak masalah. Para dokter telah melakukan pekerjaan sebenarnya ketika seseorang mengatakan “ya” beberapa minggu yang lalu.

Dokumentasi desain memperlambat kesalahan

Hal yang paling mengganggu saya tentang dokumen desain adalah dokumen tersebut menunda satu aktivitas yang sebenarnya mengurangi ketidakpastian: menulis kode.

Siklus peninjauan dokumen desain sebagian besar perusahaan memakan waktu satu hingga dua minggu. Kadang-kadang bisa memakan waktu lebih lama jika seorang insinyur sedang berlibur atau dokumennya terjebak dalam “komentar lagi”. Selama periode tersebut, tidak ada yang menulis kodenya, tidak ada yang belajar dari implementasinya, dan tidak ada yang menemukan masalah sebenarnya.

Pengkodean selama dua minggu akan mengajarkan Anda lebih banyak tentang sistem Anda daripada dua minggu menulis. Anda akan memiliki prototipe. Anda akan tahu bagian mana yang sulit dan mana yang sepele. kamu akan memilikinya nyata Pertanyaan untuk ditanyakan daripada pertanyaan hipotetis.

“Tetapi bagaimana jika desainnya salah dan tidak ada yang mengetahuinya sampai peninjauan kode?” Itulah gunanya single pager. Pernyataan masalah dan sketsa batasan memberi tim Anda semua yang mereka perlukan untuk mengatakan, “Tunggu, ini tidak berhasil.” Jika seseorang tidak dapat menemukan arah yang salah dari dokumen maksud satu halaman, empat belas halaman pola API lagi tidak akan membantu.

Ironisnya, dokumen desain seharusnya menghemat waktu, namun dokumen tersebut memuat tahap pengembangan yang paling lambat dan paling tidak informatif dan menunda tahap yang paling cepat dan paling informatif.

Ini seperti menghabiskan dua minggu membaca ulasan restoran daripada hanya pergi makan malam. Saat Anda selesai membaca, restoran akan mengubah menunya.

“Tetapi perusahaan besar menggunakan RFC!”

Dan mereka melakukannya. Perbandingan ini akan membuat dokumen desain Anda lebih memuaskan.

Orang Asing Koordinasi RFC IETF. Mozilla, Google, dan beberapa pengembang di Siberia perlu mengimplementasikan HTTP secara mandiri dan membuat sistem mereka dapat dioperasikan. Spesifikasi awal yang terperinci adalah satu-satunya cara untuk mencapai hal ini. Anda tidak dapat mengulangi cara Anda mencapai kompatibilitas antara pihak-pihak yang tidak akan pernah berbagi basis kode.

Tim Anda berbagi saluran Slack dan repositori di GitHub. Perusahaan Anda tidak memiliki masalah koordinasi untuk membenarkan RFC. Yang ada adalah tiga insinyur yang bisa berbicara satu sama lain.

Jika Anda memiliki 50 tim yang mengintegrasikan API publik dengan mitra eksternal: Tentu saja, Anda mungkin menginginkan sesuatu yang lebih mirip dengan IETF RFC. Namun Anda mungkin juga memiliki siklus rilis 12 minggu dan memiliki pendapat yang kuat tentang Microsoft Teams, jadi pertanyaan Anda lebih penting daripada format dokumen.

Untuk lebih jelasnya, maksud saya sangat sederhana: sebagian besar perusahaan yang menulis dokumen desain panjang melakukan hal ini TIDAK Ada masalah koordinasi. Mereka memiliki tim yang terdiri dari delapan orang yang berbagi jalur penerapan.

jadi apa Ya Apakah itu layak untuk ditulis? Di bawah keseluruhan ritual terdapat dokumen berguna: satu halaman yang memuat niat dan identitas. Apa kata benda dan kata kerja di bidang ini? Apa yang berbicara dengan apa? “Kami membagi layanan pembayaran karena latensi mengganggu kami. Kami akan memodelkan transaksi sebagai peristiwa, bukan garis. Berikut adalah tiga konsep yang menjadi perhatian layanan baru ini dan bagaimana alurnya.” Hal ini membuat orang-orang tetap selaras Mengapa Dan pada syarat apa Jangan berpura-pura Anda telah menyelesaikan masalahnya. Anda belum melakukannya. Anda belum memberi tahu Claude apa yang harus dilakukan.

Ada nilai nyata dalam beberapa pemikiran awal, seperti mengartikulasikan masalah yang Anda pecahkan, menentukan keputusan mana yang sulit untuk dibatalkan, dan menguraikan batasan-batasan sistem yang seharusnya. Namun semua ini tidak memerlukan dokumen setebal 15 halaman. Cocok di atas serbet.

Masalahnya adalah serbet tidak pernah menjadi serbet. Ini berpindah ke pola API, model database, dan diagram urutan untuk setiap kasus tepi. Anda belum melakukan pivot. Anda menulis kode dalam bahasa Inggris, yang merupakan bahasa pemrograman yang lebih buruk, kecuali Anda mengetiknya di Opus 4.6.

apa yang harus dilakukan

Saya tidak menentang berpikir sebelum Anda membangun. Masalahnya terletak pada format dan granularitas pemikiran ini.

Tulis tentang masalahnya, bukan solusinya. Rich Hickey telah mengatakan ini selama bertahun-tahun. Kesalahan paling serius datang dari kesalahpahaman masalah, bukan kesalahan implementasi. Pernyataan masalah memaksa Anda untuk menghadapi apakah Anda setuju dengan apa yang Anda bangun. Apa yang rusak, untuk siapa, dan mengapa hal itu penting sekarang. Paragraf ini lebih berharga daripada diagram urutan mana pun yang pernah digambar.

Identifikasi pintu satu arah Anda. Kerangka kerja Jeff Bezos berguna di sini: beberapa keputusan tidak dapat diubah (pintu satu arah) dan patut dipertimbangkan dengan cermat. Sebagian besar bersifat reversibel (pintu dua arah) dan sepadan dengan kecepatannya. Kontrak API publik merupakan pintu satu arah. Begitu konsumen eksternal mengandalkannya, Anda berada dalam masalah. Skema database Anda adalah pintu satu arah. Memigrasikan data produksi sangatlah brutal. Batas pelayanan merupakan pintu satu arah. Penggabungan kembali layanan bahkan lebih buruk lagi. Tapi tanda tangan fungsi internal Anda, struktur folder Anda, kerangka pengujian pilihan Anda? Pintu dua arah. Berjalanlah ke sana, dan jika Anda tidak menyukai apa yang ada di seberang sana, berjalanlah kembali. Masalah dengan dokumen desain adalah dokumen tersebut memberikan tinjauan satu arah terhadap setiap keputusan, termasuk pustaka serialisasi JSON mana yang akan digunakan.

Buatlah batasan, bukan implementasi. John Ousterhout merekomendasikan untuk menghabiskan sekitar 10-20% waktu Anda untuk desain awal, khususnya Dekomposisi sistem dan desain antarmukabukan detail implementasi. Di mana antarmuka publiknya? Di mana modul bertemu? Apa yang mahal untuk dirajut dan diurai nanti? Rich Cupang menyebutnya “selesai”. Begitu Anda mengaitkan dua masalah, akan sangat menyakitkan untuk memisahkannya. semuanya di dalam Batasan adalah masalah pemfaktoran ulang. semuanya di antara Itu adalah penulisan ulang.

Puncak dulu, rekam belakangan. Habiskan dua hari untuk membuat prototipe kasar. Kemudian tulis dokumen singkat yang mendokumentasikan konten Anda dipelajari: Keterbatasan sebenarnya, bagian yang mengejutkan, keputusan yang sangat penting. Dokumen ini sepuluh kali lebih berguna dibandingkan dokumen desain pra-implementasi karena didasarkan pada kenyataan, bukan dugaan.

Periksa kode, bukan prosa. tinjauan kode Ya Tinjauan desain. Permintaan tarik adalah dokumen desain terkompilasi yang sebenarnya. Jika desainnya salah, Anda akan melihatnya di kode, dan Anda akan menemukannya lebih cepat daripada di dokumen Google yang berisi diagram urutan yang tidak akan dibaca siapa pun setelah halaman ketiga.

Jika Anda membaca ini dan berpikir “jadi saran Anda adalah menulis dokumen desain pendek”, ya. Itu sarannya. Saya baru saja menghabiskan 2.000 kata dengan alasan bahwa Anda harus menulis satu halaman, bukan lima belas. Ironinya tidak hilang pada saya.

Perbedaannya adalah apa yang masuk dan apa yang keluar. Tangkap niat, keputusan yang sulit dibatalkan, dan konteks bersama. Abaikan detail implementasi dan Anda akan tetap mendapatkan kesalahan.

Dengan kata lain, rencana perjalanan Anda harus mengatakan “Kami akan pergi ke Portugal selama dua minggu, terutama Lisbon dan Porto, dan kami ingin makan banyak makanan laut.” Ini tidak boleh mencakup jadwal menit demi menit untuk hari ketujuh. Makanan terbaik dalam perjalanan ini adalah di tempat kecil di mana tidak ada petugas hotel yang memberi tahu Anda menunya. Anda tidak dapat merencanakan hal ini. Anda hanya bisa muncul.