Cara Menulis Dokumen Desain yang Baik

• Dokumen desain adalah laporan teknis yang merangkum strategi implementasi, batasan, dan trade-off dari sebuah sistem
• Dokumen desain berperan untuk meyakinkan pembaca bahwa desain tersebut cocok untuk situasi yang dihadapi
• Susunan dokumen itu penting, dan alur yang logis harus membuat pembaca tidak merasa terkejut oleh isinya
• Melalui penyuntingan, kita perlu mengurangi kata-kata yang tidak perlu dan menghemat sumber daya konsentrasi pembaca
• Penggunaan paragraf pendek dan lampiran, serta peningkatan kemampuan menulis dokumen melalui latihan, sangat penting

---

Definisi

• Dokumen desain adalah laporan teknis yang merangkum strategi implementasi sistem dalam konteks trade-off dan batasan

Tujuan

• Dokumen desain bertujuan meyakinkan pembaca bahwa desain tersebut optimal, seperti halnya pembuktian dalam matematika membuat sebuah teorema dapat diterima
• Dalam proses desain, kegiatan menulis itu sendiri meningkatkan ketelitian berpikir
• Dengan menulis dokumen desain, gagasan yang samar bisa diubah menjadi pemikiran yang konkret

Pengorganisasian

• Susunan dokumen desain yang baik sama pentingnya dengan pengorganisasian kode
• Seperti pemula yang menulis kode, banyak orang cenderung membuat 'dokumen desain spaghetti'
• Jika kalimat hanya disusun tanpa urutan logis, pembaca akan sulit mengikuti konteks dan menjadi bingung
• Dokumen yang sempurna harus memiliki alur yang alami sehingga pembaca tidak terkejut, dan setiap kalimat harus berlanjut secara wajar berdasarkan isi sebelumnya
• Tujuannya adalah memahami keadaan berpikir pembaca lalu membimbingnya secara bertahap ke keadaan yang baru
• Keberatan yang bisa diperkirakan harus diselesaikan lebih dulu; penjelasan harus datang sebelum pembaca sempat mengajukan sanggahan

Penyuntingan

• Setelah isi tertata dengan baik, tahap menghapus kata-kata yang tidak perlu (penyuntingan) menjadi penting
• Konsentrasi pembaca adalah sumber daya yang terbatas, sehingga informasi yang tidak perlu harus dibuang dengan tegas
• Dari draf awal, sekitar 30% ungkapan yang tidak bermakna bisa dikurangi
• Dengan menyunting dokumen orang lain dan melatih sudut pandang kritis, kita juga bisa merapikan tulisan sendiri dengan lebih efisien
• Berlatih dengan tweet pendek (batas 280 karakter) juga membantu menyederhanakan pemikiran dan meningkatkan kemampuan merangkum

Pengalaman dan Latihan

• Tidak ada jalan pintas yang lebih baik untuk meningkatkan kemampuan selain latihan berulang
• Pengalaman dengan budaya kerja yang berpusat pada dokumen di Amazon sangat membantu meningkatkan kemampuan menulis dokumen
• Dalam rapat penting, digunakan cara membagikan dokumen desain sepanjang 1–6 halaman terlebih dahulu, lalu semua orang membacanya dalam diam dan menuliskan pendapat di margin
• Dengan menerima umpan balik, kemampuan menulis dapat ditingkatkan secara nyata

Tips Konkret

Gunakan paragraf pendek

• Dokumen desain harus membangun alur dengan bullet point yang ringkas dan berurutan
• Setiap bullet point (observasi, ide, masalah, perbaikan, dan sebagainya) disusun sebagai paragraf pendek yang berfokus pada satu konsep
• Setiap paragraf harus cukup jelas untuk diringkas menjadi satu kalimat; ini membantu menghemat sumber daya memori jangka pendek pembaca

Manfaatkan lampiran

• Perhitungan yang rumit atau hasil simulasi sebaiknya dirapikan secara rinci di lampiran, bukan di isi utama dokumen, dan cukup disebutkan secara singkat dalam bentuk catatan kaki di bagian utama
• Lampiran tidak wajib untuk memahami kesimpulan utama isi dokumen, tetapi disediakan agar pembaca yang penasaran bisa merujuknya

Contoh penyuntingan

• (Sebelum disunting, paragraf bertele-tele):

  Setiap bullet point harus menjadi paragraf terpisah dalam dokumen. Setiap paragraf harus bisa diringkas menjadi satu kalimat. Tidak harus benar-benar hanya satu kalimat, karena penjelasan tambahan bisa dimasukkan untuk menjelaskan konsep. Namun, setelah membacanya, pembaca tetap harus bisa merangkumnya menjadi satu kalimat.

• (Sesudah disunting, paragraf yang dipadatkan):

  Setiap bullet point harus berupa satu paragraf yang bisa diringkas menjadi satu kalimat. Tidak harus benar-benar hanya satu kalimat, dan bila perlu penjelasan tambahan bisa ditambahkan. Namun setelah dibaca, isinya harus tetap bisa dipadatkan menjadi satu kalimat.

Penutup

• Dokumen desain adalah proses penting untuk membangun kemampuan melalui ketelitian berpikir, alur logis, penyuntingan yang berpusat pada pembaca, dan latihan berulang

[GN⁺]

Komentar Hacker News

• Memperkenalkan dua kutipan dari artikel yang terasa sangat berkesan. Yang pertama adalah kalimat pada tangkapan layar X: "ide menjadi 10 kali lebih baik selama proses menulis". Yang kedua adalah pernyataan di bagian awal: "orang terpenting yang harus diyakinkan adalah penulis itu sendiri". Mengejutkan bahwa meski sudah bertahun-tahun bekerja di industri ini, masih ada orang yang menentang perlunya dokumen desain. Leslie Lamport pernah berkata bahwa "menulis adalah cara alam memberi tahu kita betapa berantakannya cara kita berpikir". Jika ingin meningkatkan kemampuan menulis teknis, artikel Write Like an Amazonian(https://medium.com/@apappascs/…) layak direkomendasikan
  • Nasihat "ubah kata sifat menjadi data" tampaknya sudah menyebar ke seluruh industri teknologi, sampai-sampai akhir-akhir ini setiap resume yang kulihat penuh angka dan malah membuat bingung apa maknanya
• Sebagai reviewer desain, ada hal yang menurutku wajib diinternalisasi oleh setiap penulis dokumen. Yaitu bagian yang mengatakan, "dokumen yang baik membuat pembaca memahami masalah dan model berpikirnya, sehingga ketika solusi yang lahir dari berminggu-minggu perenungan akhirnya diperkenalkan, pembaca akan menerimanya secara alami". Kutipan favoritku adalah, "jika punya lebih banyak waktu, aku akan menulis surat yang lebih pendek". Dokumen desain harus menyederhanakan hal yang rumit; menurutku ini bukan tempat untuk menuangkan semua lika-liku dan kegagalan yang dialami developer begitu saja. Hal-hal seperti itu tentu tetap layak dicatat, tetapi lebih baik dirangkum di dokumen terpisah atau lampiran. Yang dibutuhkan adalah menunjukkan jalan ke depan secara sederhana
  • Aku lebih suka ungkapan "lebih banyak waktu, surat yang lebih pendek"
  • Aku selalu melemparkan pertanyaan seperti ini ke diriku sendiri: "apakah topik ini akan memicu perdebatan yang tidak perlu?", "apakah perdebatan itu layak dilakukan?" Tujuanku adalah membuat pembaca baru bisa ikut masuk ke diskusi tanpa kesulitan, sekaligus mencegah kontroversi pada bagian-bagian yang tidak penting
• Rapat Amazon dimulai dengan pembicara membagikan dokumen berbentuk prosa. Semua orang duduk diam membaca dokumen itu, lalu menuliskan catatan dan pertanyaan dengan pena merah di margin. Aku sendiri belum pernah bekerja di Amazon, tetapi metode ini terdengar sangat efektif, dan orang-orang yang menceritakan pengalaman ini tampaknya selalu menyukainya. Sekilas tampak tidak efisien karena waktu rapat yang berharga dipakai hanya untuk membaca bersama, padahal jika semua orang membaca dan bersiap sebelumnya, rapat bisa lebih singkat. Membaca serempak secara real-time membuat orang harus menunggu pembaca yang lebih lambat, atau menghabiskan waktu dalam kebingungan karena pemahaman tiap orang berbeda akibat kurangnya konteks. Saat melakukan design review di Google, aku sering melihat sebagian besar peserta datang tanpa persiapan, pertama kali melihat dokumen itu saat rapat, lalu langsung ikut berdiskusi. Menurutku ini karena Google tidak punya budaya dokumentasi yang kuat, dan secara implisit juga membiarkan lead tim atau manajer datang tanpa persiapan. Kalau budaya untuk benar-benar membaca sebelum rapat bisa dibentuk dengan baik, waktu rapat tampaknya bisa dipakai jauh lebih efisien
  • Orang-orang bilang jika membaca dulu sebelum rapat maka waktu rapat akan berkurang, tetapi praktik Amazon justru merupakan respons terhadap kenyataan bahwa orang pada praktiknya memang tidak membaca sebelumnya. Dari artikel lama terkait hal ini, katanya membangun budaya yang kuat agar semua orang membaca dan bersiap lebih dulu pada dasarnya mustahil. Semua peserta tidak sempat bersiap karena rapat sebelumnya, dan sebelum itu pun ada rapat lain lagi. Secara teori orang bisa mengkritik bahwa jumlah rapat seharusnya dikurangi, tetapi pada kenyataannya rapat-rapat itu tetap bernilai, dan keputusan tetap bisa diambil meski waktu membaca dihitung. Pada akhirnya kita perlu fokus pada hasil, dan tampaknya di Amazon kelebihan cara ini memang dirasa lebih besar daripada kekurangannya
  • Aku bertanya-tanya kenapa waktu kapan dokumen dibaca dianggap penting. Kalau memang butuh lebih banyak waktu, durasi rapat bisa saja diperpanjang. Kekurangannya mungkin hanya penjadwalan rapat jadi lebih sulit, tetapi total waktu yang dibutuhkan menurut pandangan ini tidak berubah
  • Menurutku jauh lebih banyak waktu terbuang ketika tidak semua orang berada pada tingkat pemahaman yang sama, atau ketika ada kekhawatiran bahwa seseorang akan melewatkan corner case
  • Ada yang menceritakan pengalaman bahwa jika sesuatu tidak benar-benar dibahas di rapat, maka tidak akan terjadi apa-apa
• Ada banyak nasihat hebat tentang kejelasan dan penyuntingan. Titik lemahnya adalah bagaimana dokumen dikelola setelah disetujui. Tanpa pengelolaan, semuanya akan merosot menjadi kondisi 'arkeologi desain'. Beberapa tahun lalu Andrew Harmel-Law mengusulkan Architecture Decision Records (ADR) sebagai cara efektif untuk mencatat keputusan arsitektur di dalam organisasi, dan pendekatan ini mungkin bisa membantu. ADR berada di samping kode (misalnya adr/001-use-postgres.md) dan mencatat konteks, keputusan, serta status secara singkat. Keuntungannya adalah bisa dengan mudah ditinjau di setiap PR, mudah diganti saat situasi berubah, dan alasan di balik keputusan awal tetap bisa dicari lagi bahkan berbulan-bulan kemudian. [Tautan: https://martinfowler.com/articles/…]
  • Dengan cara seperti ini, aku jadi penasaran apakah komite-komite tingkat organisasi seperti Security, Privacy, Compliance, dan sebagainya akan menjadi reviewer di setiap PR yang memuat ADR. Aku ragu PR seperti itu bisa merge dalam 90 hari
  • Aku harus membaca tuntas tautan MF.com(https://thoughtworks.com/radar/techniques/…) itu, tetapi "Advice Process" tampaknya berakhir begitu saja dengan kalimat 'bicara dengan semua orang'. Orang yang punya jabatan "Managing" mungkin akan kehilangan minat di titik itu. Inti sebenarnya tampaknya adalah "empat elemen pendukung", tetapi saat aku mencoba mempelajari ADR lebih lanjut lewat tautan ini, hasilnya malah berujung mengunduh PDF(https://thoughtworks.com/content/dam/…). Akan bagus jika ada definisi yang jelas tentang apa sebenarnya ADR itu
  • Session messenger adalah contoh yang representatif. Karena sudah ada begitu banyak perubahan desain dan arsitektur, tidak ada lagi informasi otoritatif yang secara resmi menjelaskan cara kerjanya. Sebagai catatan, kalau butuh secure messaging, ya pakai saja Signal
• Dalam pengalamanku, organisasi dan kejelasan adalah hambatan terbesar bagi software engineer untuk meningkatkan kemampuan menulis dokumen. Menurutku analogi 'spaghetti code' dari penulis adalah contoh bagus untuk menjelaskan pentingnya mengatur ide. Aku sendiri pernah mencoba menyampaikan hal serupa dengan cara lain, dan ke depan aku berencana memakai analogi ini. Aku juga pernah menulis posting blog yang mirip(https://ryanmadden.net/things-i-learned-at-google-design-docs/); kesamaan seperti kepadatan informasi dan pentingnya latihan, serta perbedaan antar perusahaan, terasa menarik. Soal argumen 'paragraf pendek', aku agak punya pandangan berbeda. Paragraf pendek muncul karena informasinya dirapikan dengan baik; sekadar memecah baris saja tidak benar-benar membantu. Menurutku bagian 'Editing' justru menjelaskan gagasan dasarnya dengan lebih baik
• Ada satu proses yang kupakai. Langkah 1: tuangkan saja semua yang terpikir ke dalam dokumen secara acak (mencoba dikte suara juga boleh). Langkah 2: biarkan LLM (large language model) mencoba menyusun struktur dan alurnya. Sebenarnya di tahap ini hasilnya pun bisa saja dibuang; ini tetap bagian dari proses menyempurnakan pikiran. Langkah 3: dengan merujuk pada hasil LLM, atau dengan membuat outline baru sepenuhnya, tulis draf pertama. Langkah 4: buat seteringkas mungkin dengan mengurangi kata, mengganti dengan kata yang lebih mudah, dan sebagainya. Langkah 5: ulangi langkah 4. LLM berperan sebagai jembatan yang menata draf yang masih berantakan. Kita juga harus siap membuang apa yang dihasilkan LLM. Paling tidak 30% selalu bisa dipangkas. Setiap kali melihat bahwa tulisan bisa dipersingkat tanpa kehilangan makna, aku tetap merasa kagum
  • Aku merasa proses menyunting ulang tulisanku sendiri sama pentingnya dengan menulisnya pertama kali. Di tahap ini aku bisa melihat seberapa tergesa-gesa aku menarik kesimpulan, dan hal-hal apa yang belum kupertimbangkan. Banyak orang tampaknya belum cukup menghargai tulisan sebagai alat untuk memusatkan pikiran. Hal yang sama juga berlaku untuk kode. Bahkan kalau hanya menulis template sederhana, sering kali saat menulis test code muncul ide untuk memperbaiki kode utama. Tetapi LLM tidak akan menunjukkan peluang perbaikan kualitatif seperti ini
  • Ini proses memperluas, memendekkan, memadatkan, memperluas lagi, lalu memadatkan lagi secara berulang. Ketika seseorang mengajukan pertanyaan spesifik, kita memperluas lagi, dan pada akhirnya memakai LLM untuk membuat ringkasan santai demi kesenangan. Kita ini benar-benar sedang naik roller coaster tanpa akhir
• Aku merasa harus lebih sering menulis. Dua metode struktur dokumen yang paling mewakili menurutku adalah B.O.O. dan Good Strategy/Bad Strategy. B.O.O. adalah singkatan dari Background, Objective, Overview, dan digunakan untuk merangkum bagaimana alurnya sampai ke titik ini serta apa yang ingin diubah dan bagaimana caranya. Good Strategy/Bad Strategy adalah buku yang tersusun atas diagnosis, guideline/prasyarat/persyaratan, dan action; dari sisi pengorganisasian dokumen, ini mirip dengan B.O.O. B.O.O. cocok untuk Google atau organisasi dengan anggota yang sedikit, sedangkan Good Strategy/Bad Strategy bisa diterapkan pada skala yang jauh lebih beragam, tetapi membutuhkan penulis yang benar-benar kuat
• Setelah mengikuti kelas penulisan teknis, kemampuanku merangkum inti dengan jelas meningkat drastis. Fokusnya pada metode 'coret dengan pena merah' (menulis, mencoret, lalu menulis ulang), dengan penekanan pada cara menyampaikan konsep dengan kata sesedikit mungkin. Proses ini terbagi ke dalam beberapa tahap, dan makin sering dilatih, makin mudah dilakukan. Aku juga berusaha membagikan kemampuan ini kepada rekan satu tim, sambil terus mengingatkan bahwa ini adalah keterampilan yang perlu dilatih secara rutin
• Aku sangat menyukai dokumen yang ditulis dengan cara seperti ini, begitu juga budaya menulisnya sendiri. Namun, aku juga pernah melihat pendekatan ini berbalik merugikan. Menjelaskan alasan dan logika yang mengantar ke sebuah kesimpulan sangat efektif untuk dokumen persuasif. Tetapi tidak selalu persuasi semacam itu diperlukan. Kadang justru lebih baik menuliskan kesimpulannya dulu secara langsung, terutama bagi pembaca yang sudah mempercayai penulisnya. Dalam banyak kasus, pembaca lebih ingin tahu intinya dulu daripada lelah mengikuti logikanya. Setelah tahu kesimpulannya, barulah mereka ingin mengikuti rincian logikanya
  • Menaruh ringkasan di atas lalu melanjutkan dengan penjelasan dan dasar pemikiran di bawahnya juga struktur yang sangat masuk akal
• Aku cukup sering menulis dokumen desain yang mungkin cuma akan kubaca sendiri. Tetap saja terasa kuat hanya dengan meninggalkan dokumen itu dalam bentuk tulisan. Kalau ada contoh dokumen nyata, itu akan sangat membantu; aku ingin membandingkan struktur dokumen versiku dengan struktur akhir milik orang lain