Belajar Solution Architect - Documentation & Handoff

#Pendahuluan

Setelah di episode 9 estimasi biaya solusi kalian lolos review dengan asumsi transparan dan unit economics per tiket, sekarang kita bahas kompetensi yang menentukan apakah semua kerja keras itu benar-benar terwujud: dokumentasi dan handoff. Solusi terbaik di dunia akan dieksekusi salah jika dokumennya tidak dibaca — dan dokumen paling detail pun sia-sia jika tim delivery menebak-nebak niat architect.

Mengapa ini penting? Karena SA jarang ikut menulis semua kode. Kualitas eksekusi kalian dipindahkan lewat artefak: SDD, diagram, ADR, dan sesi handoff. Dokumen yang buruk = desain yang buruk di mata tim, seberapa pun cemerlang isinya di kepala kalian.

#Prinsip Dokumentasi yang Benar-Benar Dibaca

Empat prinsip yang membedakan dokumen hidup dari dokumen museum:

1. Tulis untuk pembaca spesifik — SDD untuk engineer dan reviewer; exec summary satu halaman untuk sponsor. Satu dokumen mencoba melayani semua orang biasanya dilupakan semua orang.
2. Keputusan lebih penting daripada deskripsi — pembaca bisa membaca kode untuk tahu bagaimana; mereka butuh dokumen untuk tahu mengapa. Prioritaskan konteks, trade-off, dan batasan.
3. Dokumen tinggal dekat kode — simpan di repository (Markdown), direview via pull request, diperbarui di commit yang sama dengan perubahan arsitektur. Wiki terpisah yang tak tersinkron adalah kebohongan terorganisir.
4. Sekecil mungkin tapi cukup — setiap halaman harus punya alasan eksistensi. SDD 8-15 halaman dengan diagram tepat selalu mengalahkan 60 halaman prosa.

#Struktur SDD Final

Kerangka dari episode 2 kini kita matangkan menjadi struktur final. Ini pola yang sudah terbukti bekerja lintas organisasi:

# [Nama Solusi] — Solution Design Document
 
0. Executive Summary      : masalah, solusi dalam 5 kalimat, biaya, risiko utama
1. Konteks & Tujuan       : latar bisnis, tujuan terukur, stakeholder
2. Requirements           : FR / NFR / Constraints (dari episode 3)
3. Arsitektur             : C1 konteks -> C2 container -> C3 komponen
                            + sequence alur kritis + data flow
4. Keputusan Penting      : tabel ringkas merujuk ADR-xxxx
5. Estimasi Biaya         : asumsi, breakdown, skenario peak (episode 9)
6. Security & Compliance  : threat model ringkas, kontrol (episode 8)
7. Operabilitas           : monitoring, alerting, runbook singkat,
                            backup & DR pointer (episode 15)
8. Risiko & Mitigasi      : risiko | dampak | mitigasi | owner
9. Rencana Delivery       : milestone, dependensi, PoC status
10. Lampiran              : glossary, referensi, diagram detail

Bagian 7 (Operabilitas) sering dilupakan SA padahal justru bagian ini yang membuat tim ops menyayangi kalian: metrik apa yang dipantau, ambang alert berapa, apa langkah pertama saat alarm bunyi.

#Diagram C4: Satu Model, Empat Zoom

Standar visualisasi yang paling praktis untuk dokumentasi solusi adalah model C4 — seperti zoom peta dari satelit ke jalanan:

Aturan praktisnya: C1 untuk semua orang, C2 adalah diagram inti SDD, C3 hanya jika modul internal rumit. Contoh C2 untuk studi kasus tiket:

Kaidah gambar yang menjaga diagram tetap terbaca: satu diagram satu cerita; label teknologi pada kotak; panah data/alur berarah; konsisten bentuk (kotak=proses, silinder=data, hexagon=queue). Simpan sumber .drawio di repo bersama ekspor PNG — diagram yang tidak bisa diedit ulang pasti usang.

#Menata ADR Sejak Awal

ADR (episode 4) berkembang menjadi log keputusan proyek. Disiplin penataannya:

• Nomor urut permanen (0001-, 0002-, ...); keputusan dicabut dengan ADR baru, bukan mengedit yang lama — sejarah adalah data.
• Status eksplisit: Proposed → Accepted → (opsional) Superseded by ADR-0009.
• Satu keputusan satu file; keputusan besar boleh merujuk keputusan pendukung.

docs/adr/
├── 0001-modular-monolith-event-queue.md   (Accepted)
├── 0002-postgresql-dan-cdc-ke-warehouse.md (Accepted)
├── 0003-tokenisasi-pembayaran-tanpa-pci.md (Accepted)
├── 0004-opensearch-untuk-search.md          (Accepted)
└── 0005-multi-region-ditunda.md             (Superseded by 0009)

Saat reviewer baru bergabung enam bulan kemudian, ia membaca sepuluh file pendek itu alih-alih menginterogasi kalian semalaman.

#Handoff ke Tim Delivery

Handoff bukan mengirim email berisi PDF. Ini proses bertahap:

1. Walkthrough desain (90-120 menit) — presentasikan C1-C2, keputusan utama, dan risiko. Rekam sesinya; video itu onboarding emas untuk anggota baru.
2. Sesi Q&A terstruktur — minta tim mengkritik desain: skenario failure mana yang belum terjawab? Temuan masuk sebagai update SDD atau ADR baru.
3. Definisikan guardrails — hal-hal yang tidak boleh dilanggar (kontrak API, model izin, naming) vs area kebebasan tim (implementasi internal modul). Guardrails ditulis, bukan diimplikasikan.
4. Sepakati mekanisme evolusi — perubahan yang menyentuh arsitektur wajib lewat proposal ADR ringkas; sisanya otonom tim. Ini mencegah dua kutub ekstrem: micromanagement dan drift tanpa kendali.
5. Architect-on-call ringan di fase awal — ketersediaan kalian dua minggu pertama eksekusi menghemat puluhan putaran salah paham.

#Common Pitfalls

• Diagram ornamen — diagram indah yang tidak menjelaskan keputusan apa pun; kalau bisa dihapus tanpa kehilangan pemahaman, hapus.
• Dokumen sekali-jadi — SDD ditulis pra-launch lalu tak pernah disentuh. Mitigasi: definition of done tiap epic termasuk update SDD bila arsitektur berubah.
• Over-dokumentasi code-level — mendokumentasikan fungsi internal yang berubah tiap sprint. Itu pekerjaan komentar kode dan test, bukan SDD.
• Handoff monolog — presentasi satu arah tanpa sesi kritik; hasilnya tim "setuju" tanpa paham, lalu eksekusi melenceng diam-diam.
• Bahasa ambigu — kata "cepat", "aman", "scalable" tanpa angka. Ingat episode 3: tanpa metrik, itu harapan.

#Penutup

Inti yang harus dibawa pulang:

• Tulis untuk pembaca tertentu, prioritaskan mengapa, tinggalkan dokumen di repository dekat kode.
• SDD final 11 bagian dari executive summary sampai rencana delivery; operabilitas adalah bagian yang paling sering hilang.
• C4 memberi zoom yang tepat per audiens: C1 context untuk semua, C2 container sebagai inti SDD.
• ADR ditata sebagai log bernomor permanen — sejarah keputusan adalah aset.
• Handoff = walkthrough + sesi kritik + guardrails tertulis + mekanisme evolusi; sukses bila tim mandiri menjelaskan "mengapa".

Di episode 11 selanjutnya kita akan membahas stakeholder communication — cara menerjemahkan materi teknis untuk audiens non-teknis, struktur presentasi solusi yang meyakinkan, mengelola pertanyaan sulit dan konflik prioritas, serta teknik negosiasi trade-off dengan manajemen. Sampai jumpa di episode 11!