Budaya Penulisan Dokumen Design Docs di Google (2020)

• Design docs adalah salah satu elemen inti dari budaya rekayasa perangkat lunak Google, yaitu dokumen yang relatif informal dan ditulis oleh penulis utama sebuah sistem atau aplikasi perangkat lunak sebelum memulai proyek pengkodean
  • Dokumen ini mencatat strategi implementasi tingkat tinggi dan keputusan desain utama, dengan penekanan khusus pada trade-off yang dipertimbangkan saat mengambil keputusan tersebut
  • Tugas software engineer bukanlah menulis kode, melainkan memecahkan masalah, dan teks tidak terstruktur seperti Design doc pada tahap awal proyek bisa menjadi alat pemecahan masalah yang lebih ringkas dan lebih mudah dipahami daripada kode

Peran Design docs dalam siklus hidup pengembangan perangkat lunak

• Selain dokumentasi desain perangkat lunak yang orisinal, Design docs juga menjalankan fungsi berikut:
  • Mengidentifikasi isu desain sejak dini ketika perubahan masih murah dilakukan
  • Membangun kesepakatan tentang desain di dalam organisasi
  • Memastikan pertimbangan cross-cutting concern
  • Menyebarkan pengetahuan engineer senior ke seluruh organisasi
  • Membentuk dasar bagi memori organisasi atas keputusan desain
  • Berperan sebagai artefak ringkasan dalam portofolio teknis seorang perancang perangkat lunak

Struktur Design doc

• Karena Design doc adalah dokumen informal tanpa pedoman konten yang ketat, aturannya adalah menulisnya dalam format yang paling sesuai untuk proyek tertentu
  • Context and scope: memberikan gambaran tentang latar belakang pembangunan sistem baru dan apa yang benar-benar akan dibangun
  • Goals and non-goals: mencantumkan tujuan sistem dan hal-hal yang bukan tujuannya
  • The actual design
    • System-context-diagram: diagram yang menunjukkan sistem sebagai bagian dari lingkungan teknis yang lebih besar
    • APIs: sketsa API yang diekspos oleh sistem
    • Data storage: membahas cara data disimpan/dikelola
    • Code and pseudo-code: hanya disertakan saat menjelaskan algoritma baru
    • Degree of constraint: tingkat keterbatasan dalam ruang solusi adalah salah satu faktor utama yang memengaruhi bentuk dokumen desain
  • Alternatives considered: mencantumkan desain alternatif yang secara wajar dapat mencapai hasil serupa, lalu menjelaskan trade-off tiap desain dan alasan memilih desain utama
  • Cross-cutting concerns: menjelaskan bagaimana kepentingan bersama organisasi seperti keamanan, privasi, dan observabilitas memengaruhi desain

Kapan menulis Design doc

• Apakah perlu menulis Design doc bergantung pada apakah manfaat seperti kesepakatan organisasi atas desain, dokumentasi, dan review senior lebih besar daripada pekerjaan tambahan untuk menulis dokumen
  • Jika tidak ada ambiguitas pada solusi untuk masalah desain akibat kompleksitas masalah atau kompleksitas solusi, nilai dari dokumentasi menjadi kecil
  • Design doc yang mendekati manual implementasi bisa jadi tidak diperlukan
  • Untuk prototyping dan iterasi cepat, overhead penulisan Design doc mungkin tidak cocok

Siklus hidup Design doc

1. Creation and rapid iteration: menulis dokumen dan melakukan iterasi cepat dengan rekan kerja untuk menghasilkan versi yang stabil
2. Review: dibagikan ke audiens yang lebih luas untuk ditinjau
3. Implementation and iteration: memperbarui dokumen jika ada perubahan desain selama implementasi
4. Maintenance and learning: berperan sebagai titik masuk yang paling mudah diakses untuk memahami sistem

Opini GN⁺

• Design doc adalah cara yang baik untuk mendapatkan kejelasan dan membangun kesepakatan dalam menyelesaikan masalah paling sulit pada proyek perangkat lunak yang kompleks. Dengan riset di muka, dokumen ini dapat menghindarkan pengkodean yang tidak perlu sehingga menghemat biaya, tetapi pada saat yang sama juga menimbulkan biaya karena memerlukan waktu untuk penulisan dan review
• Karena itu, keputusan untuk menulis Design doc harus dipilih secara bijak sesuai proyek. Jika ada ketidakpastian dalam desain perangkat lunak, keterlibatan awal engineer senior akan membantu, diperlukan kesepakatan organisasi atas desain, tim sering mengabaikan kepentingan bersama seperti keamanan, atau dibutuhkan dokumen high-level untuk desain sistem legacy, maka penulisan Design doc layak dipertimbangkan
• Ini adalah contoh yang dengan baik menunjukkan pentingnya dokumentasi dalam proses desain perangkat lunak, dan tampaknya akan membantu terutama dalam membangun budaya desain yang konsisten di tim berskala besar. Namun, karena beban dokumentasi bisa membuat engineer enggan, penting untuk menyiapkan pedoman dengan tingkat dan cakupan yang sesuai dengan situasi
• Secara pribadi, saya melihat kegunaan Design doc sangat besar dalam hal 1) mempertimbangkan trade-off sesuai kompleksitas desain, 2) menemukan isu desain lebih awal sebelum implementasi, dan 3) menyediakan gambaran sistem agar anggota baru bisa belajar dengan cepat. Namun, perlu berhati-hati agar dokumen tidak menjadi terlalu formal atau terlepas dari implementasi nyata
• Membatasi kewajiban Design doc pada tahap awal proyek atau tahap desain dengan kompleksitas tinggi, sambil memberi insentif agar engineer dapat menulisnya secara sukarela, juga bisa menjadi pendekatan yang baik. Akan baik pula jika ditekankan bahwa penulisan dokumen juga membantu memperkuat portofolio teknis engineer

[GN⁺]

Komentar Hacker News

Berbagai pendapat tentang budaya dokumen desain di Google:

• Penulisan dokumen desain telah berubah menjadi alat untuk promosi, sehingga cenderung ditulis dengan mempertimbangkan komite promosi alih-alih orang yang benar-benar membangun sistem
• Jenis-jenis dokumen desain:
  • Dokumen desain untuk promosi: lebih menekankan betapa hebatnya proyek dan perusahaan daripada tujuan proyek
  • Dokumen desain turbo encapsulator: penuh dengan jargon teknis yang sulit dipahami
  • Dokumen desain karyawan baru: isinya minim, tetapi sangat panjang
  • Dokumen desain yang penuh fakta tanpa dasar: memakai fakta yang "semua orang tahu" sebagai landasan, padahal sebenarnya belum terverifikasi
• Perancangan adalah bagian dari proyek pengodean, jadi merencanakan semuanya dalam dokumen sebelum mulai menulis kode adalah pendekatan yang keliru
• Menulis dokumen di awal hanya memberi alasan untuk mengkritik hal-hal sepele, sedangkan masalah penting lebih baik diselesaikan lebih dulu dengan berkomunikasi dengan pihak terkait
• Jauh lebih berguna jika dokumen terus diperbarui secara kolaboratif
• Tenaga kerja yang terbuang untuk dokumen desain mencapai tingkat yang sangat besar
• Budaya dokumen desain di Amazon sangat baik, tetapi di perusahaan lain yang meniru budaya ala Google justru terasa tidak bermakna
• Ada kasus ketika proyek tetap dijalankan tanpa persetujuan, tetapi umpan balik untuk dokumen desain baru diberikan belakangan
• Dokumen desain malah menggantikan dokumentasi yang sebenarnya, sehingga justru menimbulkan masalah dokumentasi yang buruk
• Dokumen desain juga punya kelebihan: membantu merapikan pemikiran, menemukan kekurangan, melancarkan komunikasi, dan memperkirakan beban kerja