Budaya Penulisan Dokumen Design Docs di Google (2020)
(industrialempathy.com)- Di Google, Design Doc adalah dokumen yang merangkum konteks masalah, strategi implementasi tingkat tinggi, dan keputusan desain utama sebelum coding, untuk mengurangi risiko saat biaya perubahan desain masih rendah
- Nilai dokumen ini bukan pada penjelasan kode yang sudah selesai, melainkan pada pengungkapan trade-off dan alternatif, sehingga organisasi berbagi dasar pertimbangan yang sama
- Design Doc yang baik memuat konteks dan cakupan, sasaran dan non-sasaran, desain aktual, alternatif yang dipertimbangkan, serta perhatian lintas bidang seperti keamanan, privasi, dan observability sesuai proyek
- Jika desain sudah jelas atau dokumen hanya mencantumkan prosedur implementasi, overhead penulisan dan review Design Doc bisa lebih besar daripada manfaatnya
- Dokumen berlanjut dari penulisan, review, pembaruan selama implementasi, hingga pemeliharaan dan pembelajaran; jika desain berubah sebelum rilis, sebaiknya dokumen juga ikut diperbarui
Peran Design Doc
- Di Google, Design Doc adalah dokumen yang relatif informal yang dibuat oleh penulis utama sistem atau aplikasi perangkat lunak sebelum memulai proyek coding
- Dokumen ini memuat strategi implementasi tingkat tinggi dan keputusan desain utama, tetapi yang penting bukan sekadar daftar keputusan, melainkan trade-off yang menunjukkan mengapa pilihan tersebut diambil
- Tujuan software engineering bukanlah memproduksi kode itu sendiri, melainkan memecahkan masalah; karena itu, pada tahap awal proyek, teks tidak terstruktur bisa lebih ringkas dan lebih mudah dipahami daripada kode
- Design Doc memiliki beberapa peran dalam siklus hidup pengembangan
- Menemukan isu desain lebih awal saat biaya perubahan masih rendah
- Membentuk kesepakatan desain di dalam organisasi
- Membantu agar perhatian lintas bidang seperti keamanan, privasi, dan observability tidak terlewat
- Memperluas pengetahuan engineer senior ke dalam organisasi
- Meninggalkan memori organisasi atas keputusan desain
- Menjadi artefak yang merangkum portofolio teknis sang desainer
Struktur dasar Design Doc
- Design Doc tidak memiliki template yang kaku; prinsip pertama adalah memilih format yang paling sesuai untuk proyek tertentu
- Namun struktur yang sering berguna dapat dirangkum sebagai konteks dan cakupan, sasaran dan non-sasaran, desain aktual, alternatif yang dipertimbangkan, perhatian lintas bidang, dan panjang yang tepat
-
Konteks dan cakupan
- Memberikan gambaran kasar tentang lingkungan tempat sistem baru akan berada dan apa yang sebenarnya akan dibuat
- Karena bukan dokumen kebutuhan, bagian ini harus ringkas dan berfokus agar pembaca cepat memahami latar belakang
- Sebagian pengetahuan awal dapat diasumsikan, dan detail dapat ditautkan melalui link
- Bagian ini harus berfokus pada fakta latar belakang yang objektif
-
Sasaran dan non-sasaran
- Merangkum sasaran sistem dan, kadang yang lebih penting, non-sasaran dalam daftar bullet singkat
- Non-sasaran bukan sekadar negasi dari sasaran seperti “sistem tidak boleh crash”, melainkan hal-hal yang bisa saja menjadi sasaran tetapi secara eksplisit dikecualikan
- Dalam desain database, kepatuhan ACID adalah contoh bagus dari hal yang perlu diketahui apakah termasuk sasaran atau non-sasaran
- Meski termasuk non-sasaran, jika tidak ada trade-off yang menghambat pencapaian sasaran, solusi yang menyediakan sifat tersebut tetap dapat dipilih
Cara menulis desain aktual
- Bagian desain aktual harus dimulai dari ikhtisar lalu turun ke detail
- Design Doc adalah tempat untuk mencatat trade-off yang muncul dalam desain perangkat lunak
- Berdasarkan fakta berupa konteks serta kebutuhan berupa sasaran dan non-sasaran, dokumen harus mengusulkan solusi dan menunjukkan mengapa solusi tertentu paling baik memenuhi sasaran
- Keunggulan format dokumen adalah fleksibilitas dalam memilih cara penyajian yang sesuai dengan kumpulan masalah
-
Diagram konteks sistem
- Dalam banyak dokumen, system-context-diagram dapat berguna
- Diagram ini menampilkan sistem sebagai bagian dari lingkungan teknis yang lebih besar, sehingga pembaca memahami desain baru dalam lingkungan yang sudah mereka kenal
-
API dan penyimpanan data
- Jika sistem yang didesain mengekspos API, umumnya baik untuk membuat sketsa API tersebut
- Sebaiknya hindari menyalin dan menempel definisi interface atau data formal apa adanya
- Definisi semacam ini mudah menjadi bertele-tele, memuat detail yang tidak perlu, dan cepat usang
- Fokuslah pada bagian yang terkait dengan desain dan trade-off
- Sistem yang menyimpan data harus membahas bagaimana data disimpan dan dalam bentuk kasar seperti apa
- Daripada menempelkan seluruh definisi skema, lebih baik menjelaskan bagian yang terkait dengan pertimbangan desain
-
Kode dan pseudocode
- Sebaiknya hampir tidak memasukkan kode ke dalam Design Doc
- Kecuali saat menjelaskan algoritme baru, pseudocode juga sebaiknya jarang digunakan
- Jika ada prototipe yang menunjukkan bahwa desain dapat diimplementasikan, prototipe tersebut dapat ditautkan seperlunya
Tingkat batasan mengubah bentuk dokumen
- Salah satu faktor utama yang memengaruhi desain perangkat lunak dan bentuk Design Doc adalah tingkat batasan dalam ruang solusi
- Di satu ujung ada proyek perangkat lunak greenfield yang hanya memiliki sasaran, sementara solusinya bisa apa saja
- Dokumen semacam ini bisa mencakup ruang yang luas, tetapi harus cepat mendefinisikan aturan untuk mempersempitnya menjadi kumpulan solusi yang dapat dikelola
- Di ujung lain ada sistem dengan solusi-solusi yang mungkin sudah terdefinisi dengan baik, tetapi belum jelas bagaimana mengombinasikannya untuk mencapai sasaran
- Bisa berupa sistem legacy yang sulit diubah
- Bisa berupa desain library yang harus bekerja dalam batasan bahasa pemrograman host
- Dalam kasus seperti ini, pekerjaan yang relatif mudah dilakukan dapat didaftar, tetapi pekerjaan tersebut harus dikombinasikan secara kreatif untuk mencapai sasaran
- Jika beberapa solusi semuanya tidak sempurna, dokumen harus berfokus pada pemilihan pendekatan terbaik berdasarkan trade-off yang telah diidentifikasi
Alternatif dan perhatian lintas bidang
-
Alternatif yang dipertimbangkan
- Bagian ini mencantumkan desain alternatif yang secara masuk akal bisa mencapai hasil serupa
- Fokusnya harus pada trade-off yang diciptakan tiap desain dan bagaimana trade-off tersebut mengarah pada pilihan akhir
- Solusi yang tidak dipilih boleh dibahas secara ringkas, tetapi bagian ini sangat penting dalam dokumen
- Bagian ini harus menunjukkan mengapa solusi lain yang mungkin dipertanyakan pembaca kurang diinginkan jika dilihat dari sasaran proyek
-
Perhatian lintas bidang
- Melalui bagian ini, organisasi dapat memastikan perhatian lintas bidang seperti keamanan, privasi, dan observability selalu dipertimbangkan
- Biasanya ini menjadi bagian singkat yang menjelaskan bagaimana tiap perhatian memengaruhi desain dan bagaimana hal tersebut ditangani
- Tim harus menentukan perhatian apa yang akan dijadikan standar dalam konteks mereka
- Karena pentingnya hal ini, proyek Google mensyaratkan Design Doc privasi terpisah, dan ada review khusus untuk privasi dan keamanan
- Penyelesaian review diwajibkan hingga saat proyek dirilis
- Praktik terbaiknya adalah berkolaborasi sedini mungkin dengan tim privasi dan keamanan agar desain mencerminkan hal ini sejak awal
- Jika ada dokumen khusus untuk topik tersebut, Design Doc pusat dapat merujuknya tanpa mengulang detailnya
Panjang dan kapan tidak perlu menulisnya
-
Panjang yang tepat
- Design Doc harus cukup detail, tetapi cukup singkat agar benar-benar bisa dibaca oleh orang-orang sibuk
- Untuk proyek besar, sekitar 10–20 halaman tampaknya menjadi titik yang tepat
- Jika jauh lebih panjang dari itu, mungkin lebih baik memecah masalah menjadi submasalah yang lebih mudah dikelola
- Design Doc mini sepanjang 1–3 halaman juga memungkinkan
- Ini terutama berguna untuk perbaikan bertahap atau sub-tugas dalam proyek agile
- Tahapannya sama seperti dokumen panjang, tetapi lebih ringkas dan berfokus pada kumpulan masalah yang lebih terbatas
-
Kapan tidak perlu menulisnya
- Menulis Design Doc memiliki overhead
- Keputusan untuk menulisnya bergantung pada apakah manfaat seperti kesepakatan desain, dokumentasi, dan review senior melebihi biaya pembuatan dokumen
- Kriteria inti adalah apakah masalah desain bersifat ambigu
- Ambiguitas bisa berasal dari kompleksitas masalah, kompleksitas solusi, atau keduanya
- Jika tidak ambigu, nilai dari proses penulisan dokumen kecil
- Jika dokumen pada dasarnya adalah manual implementasi, Design Doc mungkin tidak diperlukan
- Jika hanya mengatakan “akan diimplementasikan seperti ini” tanpa menjelaskan trade-off, alternatif, dan pengambilan keputusan, mungkin lebih baik langsung menulis programnya
- Jika solusinya terlalu jelas sehingga tidak ada trade-off, nilai dokumen menjadi rendah
- Overhead penulisan dan review Design Doc mungkin tidak cocok untuk prototyping dan iterasi cepat
- Mengikuti metodologi agile bukan berarti tidak perlu memikirkan solusi untuk masalah yang sudah diketahui dengan benar
- Prototyping itu sendiri dapat menjadi bagian dari penulisan Design Doc, dan “sudah dicoba dan berfungsi” dapat menjadi dasar kuat bagi pilihan desain
Siklus hidup Design Doc
- Siklus hidup Design Doc terdiri dari empat tahap
- Penulisan dan iterasi cepat
- Review
- Implementasi dan iterasi
- Pemeliharaan dan pembelajaran
-
Penulisan dan iterasi cepat
- Dokumen ditulis oleh penulisnya sendiri atau bersama rekan penulis
- Setelah itu, dokumen dibagikan kepada rekan yang paling memahami ruang masalah dan diiterasi dengan cepat
- Pertanyaan klarifikasi dan saran dari rekan mengarahkan dokumen menuju versi pertama yang relatif stabil
- Di Google, ada engineer dan tim yang lebih suka membuat dokumen dengan alat version control dan code review, tetapi sebagian besar Design Doc ditulis di Google Docs dan banyak memanfaatkan fitur kolaborasinya
-
Review
- Pada tahap review, dokumen dibagikan kepada pembaca yang lebih luas daripada penulis asli dan kolaborator dekatnya
- Review dapat menambah nilai besar, tetapi juga dapat menjadi perangkap overhead, sehingga harus ditangani dengan hati-hati
- Cara yang ringan adalah mengirim dokumen ke mailing list tim yang lebih luas agar orang-orang punya kesempatan meninjaunya
- Diskusi terutama berlangsung di thread komentar dokumen
- Cara yang berat adalah rapat review desain formal, di mana penulis mempresentasikan dokumen di depan pembaca yang merupakan engineer senior
- Banyak tim di Google memiliki rapat rutin untuk review semacam ini
- Menunggu rapat seperti ini dapat sangat memperlambat proses pengembangan
- Hal ini dapat dikurangi dengan meminta feedback paling penting secara langsung dan tidak menjadikan review yang lebih luas sebagai blocker kemajuan
- Ketika Google masih merupakan perusahaan yang lebih kecil, praktik umumnya adalah mengirim desain ke satu mailing list pusat dan engineer senior meninjaunya saat sempat
- Pendekatan ini memiliki keunggulan dalam membentuk budaya desain perangkat lunak yang relatif seragam di seluruh perusahaan
- Seiring organisasi engineering menjadi jauh lebih besar, pendekatan tersentralisasi ini menjadi sulit dipertahankan
- Nilai utama review adalah memberi kesempatan agar pengalaman gabungan organisasi tercermin dalam desain
- Khususnya, tahap review secara konsisten membantu memastikan desain mempertimbangkan perhatian lintas bidang seperti observability, keamanan, dan privasi
- Nilai inti review bukan sekadar menemukan isu, melainkan menemukan isu pada tahap awal siklus hidup pengembangan ketika biaya perubahan masih rendah
-
Implementasi dan iterasi
- Ketika sudah cukup yakin bahwa review tambahan kecil kemungkinannya menuntut perubahan besar pada desain, saatnya memulai implementasi
- Saat rencana bertemu kenyataan, cacat, kebutuhan yang belum tertangani, dan asumsi yang terbukti salah dapat muncul sehingga perubahan desain menjadi perlu
- Dalam kasus ini, sangat disarankan untuk memperbarui Design Doc
- Sebagai aturan praktis, jika sistem yang didesain belum dirilis, dokumen wajib diperbarui
- Dalam praktiknya, orang sering gagal memperbarui dokumen, dan karena berbagai alasan praktis lain, perubahan kerap dipisahkan menjadi dokumen baru
- Akibatnya, kondisinya bisa menjadi seperti Konstitusi Amerika Serikat dengan amandemen, bukan satu dokumen yang konsisten
- Menaruh link dari dokumen asli ke dokumen amandemen semacam ini akan sangat membantu programmer pemeliharaan di kemudian hari memahami sistem target melalui arkeologi Design Doc
-
Pemeliharaan dan pembelajaran
- Saat engineer Google menghadapi sistem yang baru pertama kali mereka sentuh, pertanyaan pertama yang sering diajukan adalah “Di mana Design Doc-nya?”
- Seperti dokumen lain, Design Doc cenderung menyimpang dari kenyataan seiring waktu, tetapi sering menjadi pintu masuk paling mudah untuk mempelajari proses pemikiran yang melahirkan sistem tersebut
- Penulis sebaiknya membaca ulang Design Doc mereka sendiri setelah 1–2 tahun
- Periksa apa yang benar
- Periksa apa yang salah
- Pikirkan apa yang akan diputuskan secara berbeda jika dilakukan hari ini
- Proses menjawab pertanyaan-pertanyaan ini membantu pertumbuhan sebagai engineer dan meningkatkan kemampuan desain perangkat lunak seiring waktu
Menentukan kapan memulai dengan Design Doc
- Design Doc adalah cara yang baik untuk memperoleh kejelasan dan membentuk kesepakatan saat memecahkan masalah sulit dalam proyek perangkat lunak
- Ini dapat menghemat biaya dengan mengurangi jalan buntu dalam coding yang sebenarnya bisa dihindari melalui riset awal
- Pada saat yang sama, penulisan dan review membutuhkan waktu sehingga juga menimbulkan biaya
- Pertanyaan berikut dapat dipertimbangkan
- Apakah desain perangkat lunak yang benar belum pasti, dan masuk akal untuk menghabiskan waktu di awal demi memperoleh keyakinan?
- Apakah akan membantu jika melibatkan engineer senior pada tahap desain, karena mereka mungkin tidak dapat meninjau semua perubahan kode?
- Apakah desain perangkat lunak ambigu atau diperdebatkan sehingga kesepakatan organisasi bernilai?
- Apakah tim terkadang lupa mempertimbangkan privasi, keamanan, logging, atau perhatian lintas bidang lain dalam desain?
- Apakah organisasi sangat membutuhkan dokumen yang memberikan wawasan tingkat tinggi tentang desain sistem legacy di dalam organisasi?
- Jika menjawab “ya” untuk 3 atau lebih dari pertanyaan ini, Design Doc kemungkinan besar merupakan cara yang baik untuk memulai proyek perangkat lunak berikutnya
1 komentar
Pendapat di Hacker News
Saya meninggalkan perusahaan karena budaya dokumen desain Google
Tak lama setelah bergabung, saya menulis dokumen dengan tingkat perapian yang sangat tinggi untuk sebuah pekerjaan yang relatif sepele, sesuatu yang sudah pernah dilakukan berkali-kali di area produk lain. Seorang rekan lalu memanggil saya secara terpisah dan berkata, “Di sini kita tidak melakukannya seperti ini”
Cara yang saya ajukan sebenarnya hanya variasi kecil dari cara yang direkomendasikan, tetapi ia meminta saya “mengevaluasi lebih banyak cara untuk menyelesaikan pekerjaan ini”; ketika saya bertanya alasannya, ia menjawab, “itu menunjukkan bahwa kamu sudah mempertimbangkannya secara luas”
Di Google jelas ada pekerjaan palsu, dan saya berharap dulu masuk ke tim lain
Budaya Google berubah menjadi kultus kargo yang meniru dirinya sendiri
Beberapa perusahaan yang saya masuki setelah Google enggan membahas proses promosi secara rinci, karena mereka sudah melihat apa yang terjadi ketika orang melakukan optimasi mikro agar sesuai dengan proses itu
Karena semua orang sibuk, kita tidak bisa berbicara santai 1:1 dengan semuanya, dan jika tidak mendapatkan tinjauan stakeholder dengan benar, orang-orang yang marah bisa datang dan membuat rilis di-rollback
Dalam konteks ini, dokumen desain adalah alat komunikasi asinkron untuk topik yang padat informasi. Jika produknya sukses, 10 tahun kemudian pun Anda akan berkomunikasi lewat dokumen ini dengan orang-orang yang baru bergabung
Saya berkali-kali terselamatkan oleh dokumen desain acak dari 2010 yang menjelaskan keputusan aneh yang masih menghambat kami sampai sekarang. Mungkin tidak cocok untuk tim kecil yang lincah atau pekerjaan yang tidak terlalu kompleks, tetapi dalam budaya engineering, sekalipun sudah menjadi kultus kargo, umumnya tetap ada alasan dan konteksnya sendiri
Jika saat merancang sesuatu hanya ada satu solusi yang sedang dipertimbangkan, berarti tidak ada desain, atau desainnya belum cukup menyeluruh. Pilihan dan trade-off adalah unsur yang membentuk desain
Banyak dari orang-orang ini adalah konsultan eksternal yang sudah bekerja dengan perusahaan selama lebih dari 15 tahun, jadi karena orang yang sama mengerjakan pekerjaan yang sama, sebenarnya sudah ada standar tertentu. Meski begitu, mereka tetap berusaha membangun straw man berupa “apa yang terjadi jika orang tidak mengikuti standar”
Akibatnya, dokumen desain tidak ada atau sudah sangat usang, dan perusahaan terus mempekerjakan konsultan yang sama dari tahun ke tahun dengan biaya yang digelembungkan
Sekarang saya berada di tim yang banyak berisi Googler lama dengan masa kerja lebih dari 15 tahun, dan dokumen desain hanya ada saat diperlukan. Misalnya ketika mencakup beberapa sistem, atau ketika memang jelas kompleks karena banyak trade-off. Di luar itu, cukup seperti “tulis CLS”
Di Google, dokumen desain tampaknya menjadi masalah karena merupakan materi inti yang masuk ke paket promosi
Karena itu, dokumen ditulis dengan lebih memperhatikan komite promosi daripada pekerja sistem tersebut yang seharusnya menjadi pembaca aslinya
Setiap kali masuk perusahaan baru, saya mengusulkan untuk mulai menulis dokumen desain, dan itu langsung memberi kesan baik kepada manajemen :)
Banyak dokumen yang saya baca tampak seolah-olah keputusan yang diinginkan sudah ditetapkan sebelumnya, lalu pada awal dokumen ditempelkan dua opsi atau lebih yang dibuat-buat untuk menonjolkan keputusan itu. Misalnya satu opsi terlalu sederhana dan satu lagi over-engineered secara tidak perlu, lalu dipilih opsi yang tampak masuk akal
Karena tidak tahu dokumen desain mana yang akan dipakai dalam paket promosi, bahkan pekerjaan sekecil apa pun semuanya didokumentasikan sebagai dokumen desain. Ada konsep dokumen desain 1 halaman, tetapi biasanya berkembang dari satu halaman menjadi beberapa halaman
Dokumen desain ditulis bahkan untuk proyek berdurasi 1 minggu, dan saya pernah harus meninjau dokumen desain 20, 30, 40 halaman untuk sesuatu yang di perusahaan lain mungkin cukup selesai dengan satu tiket JIRA
Banyak orang belajar bahwa komite promosi ingin melihat “dokumen yang ditulis sendiri oleh penulisnya”, dan benar atau tidaknya hal itu, keyakinan ini membuat segalanya lebih lambat dan menghambat pembelajaran lintas pihak. Saya bahkan pernah melihat software engineer yang terisolasi selama lebih dari satu kuartal hanya untuk menulis dokumen desain
Dalam dokumen desain, desain yang sebenarnya seharusnya menjadi inti, tetapi 99% sisanya adalah definisi masalah. Terlalu sering, saat definisi masalah diperbaiki dalam review, desainnya harus dibuang dan sebagian besar dokumen harus ditulis ulang
Yang terburuk adalah ketika perbaikan definisi masalah mengungkap solusi sederhana yang tidak memerlukan desain rumit. Penulis sudah menginvestasikan banyak waktu pada desain rumit, dan secara historis banyak komite juga melihat kompleksitas semacam itu sebagai dasar promosi, sehingga mereka menolak solusi sederhana
Saya juga pernah melihat dokumen desain yang sama sekali tidak punya alternatif. Isinya hanya penjabaran padat karya tentang hal yang harus dilakukan atau hal yang ingin dilakukan seseorang
Lama-lama, jika dilihat secara samar, dokumen desain berubah seperti sistem pelacakan bug. Semua orang sedang mengerjakan dokumen desain masing-masing dan tidak mengerjakan bug. Karena bug tidak bisa membuat orang dipromosikan
Saat masuk tim baru, orang mengatakan seolah-olah cukup membaca dokumen desain, tetapi pada kenyataannya sering kali dokumen itu tidak dilacak secara terpusat. Di banyak tim, dokumen desain bukan milik tim atau proyek, melainkan milik individu, karena dengan begitu bisa dijamin bahwa orang lain tidak berkontribusi; ini juga karena komite promosi
Banyak juga dokumen desain yang tidak bisa diakses, bukan karena sangat rahasia, tetapi memang begitu saja keadaannya. Bukan berarti tim hanya punya dua atau tiga dokumen desain; ada segunung dokumen yang harus dibaca. Dengan siklus pindah kerja di Google yang sekitar 2 tahun, banyak dokumen menghilang ditelan waktu
Di perusahaan lain, ini mirip dengan mengatakan kepada orang yang baru masuk tim, “Yang kamu butuhkan tinggal membaca semua bug yang sudah ditutup atau semua pesan commit di branch utama”
Kalau di tempat lain, setelah makan siang seseorang mungkin akan ditahan, lalu bersama tim berdiri di depan whiteboard selama beberapa jam untuk mendefinisikan masalah. Para senior akan mengajari junior secara langsung bagaimana memikirkan masalah seperti ini dan melakukan iterasi dengan cepat
Sebagian besar mungkin akan ditulis di sistem pelacakan bug, atau jika pekerjaannya besar, ditulis di wiki atau folder proyek sehingga menjadi milik bersama
Semua masalah di atas bisa diperbaiki, dan saya benar-benar pernah mencoba memperbaikinya, tetapi budaya berubah perlahan. Konsep dokumen desain itu sendiri bagus, tetapi ada jebakannya, dan cara banyak orang di Google menggunakannya bukanlah jawabannya
Saya merindukan dokumen desain yang nilainya lebih besar daripada biayanya
Secara umum, saya belum pernah melihat strategi itu berhasil
Sebaliknya, ada dokumen panjang untuk memberikan konteks, yang merangkum apa yang sudah dan sedang dilakukan tim, apa masalahnya, dan sebagainya; dokumen seperti itu cenderung panjang dan dilebih-lebihkan
Saya bekerja di perusahaan yang disebutkan, tetapi pengalaman saya tidak sama dengan penulis
Ada banyak jenis dokumen desain, dan tidak ada yang menurut saya berguna. Saya jarang melihat dokumen desain yang berguna di Google. Dokumen desain terasa seperti sesuatu untuk engineer yang terlalu berorientasi prosedur
Jenis-jenis yang saya lihat kira-kira seperti ini: dokumen desain untuk promosi tidak menjelaskan apa yang ingin dipecahkan, hanya mengatakan betapa hebatnya proyek ini dan bagaimana proyek ini membuat perusahaan menjadi lebih baik. Kesimpulan logisnya adalah penulisnya harus dipromosikan
Dokumen desain turbo encabulator adalah dokumen obrolan teknis yang penuh istilah yang baru pertama kali dilihat, sehingga tidak bisa dipahami kecuali oleh senior di tim. Kadang saya bahkan tidak yakin para senior pun memahaminya
Dokumen desain lulusan baru tidak punya isi, tetapi dibuat sepanjang mungkin untuk membuktikan sesuatu oleh orang yang baru lulus kuliah. Dokumen ini tidak menyampaikan informasi, dan sering kali mengisi sekitar 70 halaman dengan copy-paste besar-besaran dari kode yang sudah ditulis
Dokumen desain fakta karangan penuh dengan “semua orang tahu”, “semua orang bilang begitu”. Tidak sejelas politisi, tetapi mendorong desainnya sendiri dengan kalimat seperti “ini mengikuti praktik yang baik”, “perangkat lunak ini lambat, maka…”. Tidak ada penjelasan siapa yang mendefinisikan praktik baik, mengapa itu praktik baik, apa yang lambat, apakah sudah diukur, atau apakah itu sekadar perasaan pengguna akhir
99% dokumen desain yang saya lihat seperti ini. Ada pengecualian, tetapi berdasarkan pengalaman saya sangat jarang. Saya heran penulis mendorong praktik ini. Namun karena dia direktur, bukan engineer, mungkin dokumen desain masuk akal di posisi itu, dan saya masih tidak tahu nilai apa yang diberikan orang-orang seperti itu
[1] https://en.wikipedia.org/wiki/Turbo_encabulator
Hal yang saya perhatikan di awal adalah dokumen desain yang disimpan di Google Docs cenderung berkualitas lebih rendah daripada yang ada di repositori version control. Saya tidak tahu apakah itu indikator tidak langsung dari waktu penulisannya, atau karena proses code review lebih ketat daripada penyuntingan Docs
Ketika saya menulis dokumen desain besar, mungkin sekitar 40 halaman, sesuai kebiasaan saya menulisnya sebagai HTML buatan tangan dan memprosesnya melalui sistem code review. Saya juga mengunggahnya ke mailing list pusat dan web server, dan senang juga mendapat umpan balik dari karyawan nomor 3. Karena tersusun berdasarkan kategori di lokasi pusat, dokumennya mudah ditemukan
Saya tidak ingat satu dokumen desain saja pernah memiliki bobot sebesar itu sampai penting untuk promosi. Promosi seharusnya soal dampak keseluruhan, bukan output tertentu. Tentu sistemnya punya cacat besar, dan keputusan yang mengejutkan dalam arti buruk juga sering muncul, tetapi saat itu saya tidak ingat membaca dokumen desain yang dioptimalkan untuk evaluasi kinerja
Jika bisa menemukan situs web berisi kumpulan dokumen desain HTML buatan tangan dari masa awal, saya sarankan untuk menelusurinya. Mungkin dokumen itu terasa lebih berguna saat sistemnya masih aktif digunakan
Beberapa dokumen lama seperti SmartASS penuh dengan penjelasan rinci tentang persamaan dan model yang mendasarinya, dan sangat membantu untuk memahami cara kerjanya serta mengapa pendekatan itu dipilih. Belakangan itu juga memengaruhi pekerjaan desain saya. Saya bukan direktur, hanya engineer biasa, dan dokumen itu benar-benar membantu
Di antara dokumen desain Chrome yang ditautkan di situs chromium.org, ada juga beberapa yang dulu membantu saya memahami strukturnya
Itu membuat developer junior memikirkan solusi terlebih dahulu dan membenarkan keputusannya, serta memungkinkan developer senior memverifikasi keputusan tersebut dan memberi umpan balik asinkron
Namun saya selalu bekerja di startup, jadi belum pernah bekerja di organisasi engineering dengan lebih dari 30–40 orang. Big Tech mungkin berbeda, tetapi pengalaman saya positif
Demikian pula, jika menjelaskannya kepada engineer lain memakan waktu lama, setidaknya sekitar 30 menit, Anda perlu menulis dokumen untuk menghemat waktu
Saya tidak mengerti bagaimana orang bisa berpikir tidak perlu menulis dokumen sama sekali
Nantinya, saat bersiap untuk promosi, dokumen kategori 2 akan ditambahi konteks yang cukup sehingga menjadi kategori 1
Dokumentasi secara umum bagus, tetapi pendekatan ini tampak cacat
Katanya “sebelum memulai proyek coding”, penulis utama sistem atau aplikasi perangkat lunak membuat dokumen yang relatif informal, padahal desain itu sendiri adalah proyek coding, dan keduanya adalah pekerjaan yang sama
Gagasan bahwa desain bisa diselesaikan sepenuhnya di atas kertas sebelum meng-commit kode itu keliru. Pendekatan dokumen desain sebenarnya juga mengakui bahwa perlu menulis sedikit kode di awal, tetapi mencoba mengotakkannya secara ketat sebagai “prototipe yang menunjukkan kelayakan implementasi desain”
Ciri besar dokumen desain di muka adalah memberi izin kepada orang-orang untuk mencari-cari masalah, alias melakukan review, sebelum coding sungguhan dimulai. Dalam pengalaman saya, akibatnya dokumen makin lama makin membengkak dengan semakin banyak catatan syarat dan pembahasan alternatif yang tidak bermakna, dan berubah dari dokumen desain menjadi dokumen “tolong biarkan saya membuat ini sekarang”
Jika ada masalah arsitektur penting yang membutuhkan perubahan arah, lebih baik berbicara dan berkolaborasi sejak awal dengan orang-orang yang tepat, daripada membuat dokumen desain terperinci lalu ditembak jatuh
Jika tetap lebih dekat dengan gagasan “dokumen yang relatif informal” dan memperbaruinya sambil berjalan, itu bisa benar-benar berguna. Sebab Anda bisa membuat sistem yang berfungsi sekaligus dokumen yang berguna. Namun itu lebih dekat dengan mendokumentasikan sebagai bagian dari proses yang berkelanjutan dan kolaboratif daripada dokumen desain
Saya Googler. Saya juga menerbitkan beberapa paper, tetapi dulu saya tidak suka menulis dokumen desain. Sejak beberapa tahun lalu, saya menyadari manfaat utamanya bagi saya
Ini membuat bagian ide yang langsung muncul bisa dikosongkan dari kepala, sehingga saya bisa beralih ke bagian yang lebih dalam dan pertimbangan yang produktif
Kekurangan jadi lebih terlihat, terutama bagi diri saya sendiri
Pikiran jadi lebih mudah dibagikan, terutama kepada orang-orang di kantor lain. Mereka biasanya memberi umpan balik yang sangat bagus
Ini membuat saya jauh lebih memahami jumlah pekerjaan yang diperlukan dibanding ketika langsung mulai coding
Biasanya juga mengungkap hal-hal yang perlu dipelajari sebelum coding, seperti sistem yang berdekatan atau pilihan teknologi yang tepat
Memang bagus juga untuk promosi, tetapi proyek yang sukses lebih baik. Karena saya sering mendengar bahwa dokumen saya berguna, rasanya saya telah menemukan jalan yang benar
Apakah ini benar-benar efektif? Apakah lebih baik daripada alternatifnya? Di mana diskusi soal itu?
Saat saya bekerja di Amazon, budaya dokumen desainnya luar biasa. Tempat kerja berikutnya tampaknya meminjam budaya engineering Google atau budaya startup umum di SF, tetapi prosedur dokumen desainnya terasa seperti lelucon yang tidak berguna
Ini adalah salah satu perangkat yang terkait dengan budaya kerja yang lebih luas. Jika bekerja sendirian, ini latihan yang mewah; jika timnya sangat besar, ini memungkinkan pemanfaatan lebih banyak keahlian di seluruh tim dan juga berfungsi sebagai dokumentasi
Ada beberapa pola kegagalan. Mengutamakan output dibanding hasil adalah ketidakselarasan klasik. Misalnya menulis dokumen 40 halaman demi promosi; itu biasanya tidak berhasil, kecuali dalam kasus yang sangat junior, ketika yang dibuktikan hanyalah kemampuan menyambung kalimat, bukan engineering yang mendalam
Ini juga bisa berlebihan untuk tim yang bekerja sendiri. Tim kecil lain bisa berkomunikasi cukup baik hanya dengan issue, misalnya Jira, dan sesi terpisah untuk menyelaraskan ide
Engineer juga harus di-onboarding tentang cara menulis dokumen desain yang efektif. Komentar teratas yang frustrasi karena upaya pertamanya tidak langsung dipuji mungkin bisa menjadi sinyal
Menulis tentang kode itu sulit, dan biasanya HN memuji latihan seperti ini. Jika bekerja dalam tim, berhati-hatilah ketika merasa pekerjaan Anda selalu hanya hal-hal yang tidak perlu dijelaskan dalam dokumen yang bisa dibagikan dan dipikirkan secara mendalam
Jika seorang investor besar menyamar dan mencoba bekerja sebagai engineer Google selama beberapa minggu, ia akan langsung menjadi investor aktivis yang menuntut Sundar dipecat
Skala potensi manusia yang terbuang karena budaya dokumen desain Google nyaris sulit dipahami
Sebagian besar pengembangan berjalan begitu saja, dan sesekali dokumen ditulis terburu-buru agar lebih mudah membenarkan CL
Mungkin satu dari sepuluh saya melihat seseorang melakukannya terlalu berlebihan, tetapi bagi software engineer rata-rata, ini bukan pemborosan waktu besar
Jika ingin membakar uang sebanyak mungkin, saya rasa perusahaan akan dirancang persis seperti ini
Budaya dokumen desain cenderung mendorong semua orang masuk ke lapisan pembenaran atas pekerjaan mereka sendiri. Budaya pembenaran adalah pola yang cukup menekan bagi inovator, meskipun diperkuat sebagai budaya oleh rekan kerja
Sistem ini cenderung menghalangi upaya visioner dan proyek yang ambisius. Upaya yang tidak berpusat pada konsensus akan ditekan, dan jika berpikir “di luar norma yang diizinkan”, Anda akan dihukum oleh kelompok
Sistem seperti ini melahirkan groupthink, dan sifatnya yang berpusat pada tradisi “cara kita bekerja” pada dasarnya memaksa situasi di mana bekerja dengan cara lain menjadi berisiko bagi karier
Di Silicon Valley ada berbagai bentuk budaya perusahaan yang bertumpu pada klise yang dibungkus istilah ‘agile’ dan ‘design thinking’, dan biasanya itu lebih mirip institusionalisasi yang berpura-pura sebagai ‘cara yang benar’, disertai elemen tambahan yang secara sosial memaksakan variasi budaya kultus engineering yang telah dicapai kampus tersebut
Saya sudah bertemu tak terhitung banyaknya orang yang pergi meskipun bekerja di Google terasa sangat nyaman, karena itu membatasi karier mereka; jumlahnya tidak sedikit
Anda mengungkapkan dengan tepat frustrasi yang saya alami di sana. Meski begitu, saya tetap ingin mendapatkan kompensasi itu lagi
Mengenai agile, saya mengenal agile sekitar 20 tahun lalu dalam bentuk eXtreme Programming, dan itu sama sekali berbeda dari kultus kargo SCRUM atau tiruannya hari ini
Pada akhirnya, itu adalah sekumpulan prinsip yang memberi kekuatan kreatif kepada developer, mencegah manajer ikut campur dalam cara kerja, dan membuat pekerjaan selesai. Sebagai gantinya, pelanggan diberi wewenang untuk mengatakan apa yang dikerjakan, kapan, dan sejauh apa
Developer membuat estimasi sendiri, dan prinsipnya adalah “jangan membangun sesuatu yang tidak diperlukan”. Tidak ada desain besar di awal; refactoring dan testing, arsitektur dan desain dimasukkan sebagai overhead berkelanjutan dalam praktik terbaik standar, bukan sebagai story atau tugas terpisah
Rapat perencanaan adalah ketika rekan-rekan menyelaraskan diri di satu ruangan, dan story dinyatakan dengan istilah nonteknis seminimal mungkin pada post-it di whiteboard. Standup benar-benar berarti orang-orang berdiri melingkar dan memberi update sangat singkat sebatas yang mungkin menarik bagi orang lain, bukan ritual untuk membuktikan bahwa hari ini sudah masuk kerja atau untuk pamer
Dalam sistem ini, desain adalah sifat yang muncul ketika sekelompok kreatif para ahli bekerja bersama. Ini tidak menyingkirkan dokumen desain dan tetap mencakup diskusi arsitektur, tetapi tidak menuntut prosedur PRD/dokumen desain yang eksplisit
Saya ingin bekerja lagi di tempat seperti itu. Google kebalikannya, dan semuanya memakan waktu terlalu lama
Perilaku palsu semacam “kami sangat pintar” ini juga salah satu bentuk kerja sia-sia. Perusahaan seharusnya fokus pada produk yang benar-benar berfungsi dan menilai diri berdasarkan itu
Saya juga seorang Googler
Sudah ada banyak komentar bagus yang mengatakan bahwa dokumen desain Google tidak berguna, tetapi saya ingin menambahkan satu sudut pandang lagi tentang masalah yang saya rasakan
Seperti yang disebutkan, dokumen desain adalah bahan untuk promosi, sehingga menghasilkan banyak sekali embel-embel. Namun, dokumen itu juga tampak seolah-olah menggantikan dokumentasi yang sebenarnya
Setiap dokumen desain hampir langsung usang begitu selesai, tetapi tim-tim menunjuk ke dokumen desain itu alih-alih menulis dokumentasi baru. Akibatnya, dokumentasi Google cukup buruk dan ketinggalan zaman
Sejujurnya, akan jauh lebih baik jika bahan promosi adalah panduan penggunaan 2 halaman tentang cara memakai sesuatu yang benar-benar ada, daripada menulis 20 halaman tentang “pekerjaan yang tidak dilakukan”
Bisakah kita melihat dokumen yang sebenarnya? Dokumen proses desain perangkat lunak tampaknya seperti rahasia yang paling dijaga ketat. Saya belum pernah melihat dokumen nyata yang bisa dipakai untuk studi kasus
Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps
Contoh: https://rfd.shared.oxide.computer/rfd/0177
Indeks utama: https://rfd.shared.oxide.computer