Cara Menggambar Diagram Arsitektur Perangkat Lunak (2022)

 (terrastruct.com)
3 poin oleh GN⁺ 2023-10-28 | 1 komentar | Bagikan ke WhatsApp
  • Diagram arsitektur yang baik mempertahankan penyampaian ide dan kolaborasi dalam jangka panjang melalui tingkat abstraksi yang tepat, tetap mutakhir, dan menghilangkan ambiguitas, bukan lewat hiasan
  • Dasarnya adalah meminimalkan jarak antar tetangga dengan menempatkan elemen yang saling terhubung berdekatan, dan semakin besar diagramnya, semakin perlu pengulangan menghapus lalu menggambar ulang
  • Simetri bukan hanya menciptakan kesan yang enak dilihat, tetapi juga memperkuat penyampaian makna, misalnya dengan menempatkan input dan output di sisi yang berbeda
  • Menjaga penyelarasan pusat pada bentuk membuat konsep yang rumit terlihat kurang rumit, dan saat menambahkan elemen baru tata letak keseluruhan tidak mudah berantakan
  • Grup kontainer berlabel memungkinkan pembedaan lingkungan seperti AWS dan Azure, abstraksi seperti implementasi ReaderWriter, serta kumpulan objek terkait seperti Cores terlihat sekilas

Syarat diagram yang tahan lama

  • Diagram yang baik tidak dihapus begitu rapat selesai, melainkan dapat terus digunakan sebagai titik acuan untuk diskusi dan pertanyaan berikutnya
  • Ada beberapa syarat umum pada diagram yang dipakai dalam jangka panjang
    • Elemen-elemennya harus berada pada tingkat abstraksi yang tepat
    • Harus tetap mutakhir
    • Tidak boleh ada ambiguitas
  • Entitas dan relasi yang sama pun bisa digambar dengan banyak cara, tetapi ada tata letak yang membantu kolaborasi sepanjang proyek dan ada yang menghilang begitu rapat selesai
  • Keindahan yang dimaksud di sini bukan hiasan seperti bayangan atau sudut membulat, melainkan keindahan fungsional yang menyampaikan pemikiran secara efektif

Prinsip untuk membuat tata letak yang mudah dibaca

  • Meminimalkan jarak antar tetangga

    • Aturan dasarnya adalah menggambar node yang saling terhubung saling berdekatan
    • Ini mudah pada diagram kecil, tetapi saat diagram membesar dan koneksi baru ditambahkan, sifat ini mudah rusak
    • Seperti saat menemukan edge case dalam kode lalu memperbaiki bagian terkait, atau menemukan item yang terlewat dalam dokumen lalu merevisi kalimatnya, diagram untuk dokumentasi juga perlu dihapus dan digambar ulang bila perlu
    • Dalam situasi wawancara, biaya menggambar ulang bisa terasa membebani, tetapi untuk dokumen yang akan dipakai banyak orang atau banyak tim, revisi berulang menghasilkan diagram yang lebih baik

  • Mencari simetri

    • Simetri sangat berkontribusi pada kesan estetis diagram, dan otak manusia cenderung menyukai simetri visual seperti pada wajah
    • Walaupun semua node sedekat mungkin dengan tetangganya, jika simetrinya kurang diagram bisa terlihat seperti gambar yang agak miring
    • Bahkan jika jarak ke tetangga pada suatu node sedikit bertambah, versi yang lebih simetris bisa terlihat lebih baik
    • Menempatkan input di satu sisi dan output di sisi lain memperkuat makna diagram sekaligus simetrinya

  • Penyelarasan pusat

    • Penyelarasan adalah elemen besar yang membuat diagram tampak rapi
    • Diagram yang rapi membuat konsep lebih jelas, sedangkan diagram yang berantakan membuat konsep tampak lebih rumit
    • Jika sejak awal meletakkan bentuk secara acak di kanvas kosong, tata letak setelahnya juga cenderung terus acak
    • Karena penyelarasan hanya bermakna di antara dua bentuk atau lebih, menjaga penyelarasan setiap kali menambahkan elemen baru akan membuat diagram secara alami tetap rapi
    • Simetri sering menghasilkan penyelarasan, tetapi tidak selalu demikian

  • Menggunakan grup kontainer

    • Membagi diagram ke dalam beberapa area berlabel membantu pembaca memahami strukturnya dengan lebih mudah
    • Kontainer dapat menambahkan informasi berikut ke dalam diagram
      • Menambahkan konteks, seperti “layanan-layanan ini berada di AWS, dan layanan-layanan ini berada di Azure”
      • Menunjukkan abstraksi, seperti “semuanya adalah implementasi dari ReaderWriter”
      • Mengelompokkan objek terkait, seperti mengikat core 1, 2, 3, 4 ke dalam kontainer “Cores”

Topik yang berlanjut di bagian berikutnya

  • Part 2 akan melanjutkan topik berikut
    • Menggambar jalur edge
    • Ukuran dan posisi label
    • Warna
    • Ikon

Bacaan terkait

1 komentar

 
GN⁺ 2023-10-28
Komentar Hacker News

  • Saya senang memakai D2 untuk membuat diagram. Mirip mermaid.js, tetapi punya lebih banyak opsi pemformatan, dan secara pribadi menurut saya sintaksnya juga lebih baik
    Saya juga menulis artikel singkat terkait ini: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • Saya merasa diagram seharusnya tidak dibuat cantik. Misalnya, warna seharusnya dipakai untuk menyampaikan makna, bukan sebagai pilihan estetis atau artistik
      Saya paham diagram perangkat lunak yang jelek tidak enak dilihat, tetapi menghiasinya mirip seperti menambahkan kurva pada grafik garis. Secara visual mungkin terlihat bagus, tetapi mengganggu data yang ingin disampaikan
    • Saya mencoba mengikuti contohnya dan hasilnya sangat keren, tetapi tidak seperti panduannya, diagram dirender dari atas ke bawah, bukan dari kiri ke kanan
      Saya merender contoh pertama x -> y menjadi SVG lalu membuka SVG saja di browser, dan mencari di seluruh dokumentasi cara mengatur perataan output, tetapi tidak menemukannya
      Karena dokumentasi panduan dan hasil sebenarnya berbeda, saya berhenti menggunakannya. Saya mencari "d2lang connection left to right" dan sampai ke https://d2lang.com/tour/layouts/, tetapi tampaknya halaman itu tidak ditautkan dari dokumen ikhtisar, jadi memasukkannya mungkin akan membantu pengunjung
    • https://flowchart.fun/ membantu saya menggambar flowchart dengan sangat cepat untuk memahami proses sistem. Yang paling saya suka adalah sifatnya yang intuitif dan cepat untuk iterasi, dan CSS kustom untuk styling juga cukup berguna
      Khusus untuk flowchart, menurut saya ini termasuk alat diagram berbasis teks yang paling mudah dan cepat dari semua yang pernah saya pakai
    • D2 punya layout engine tala yang sangat bagus, tetapi untuk menggunakannya perlu lisensi berbayar. Dua engine lainnya tidak sebagus itu
    • Saya suka dan sering memakai mermaid, tetapi sepertinya perlu juga mengecek D2. Menurut saya diagram deklaratif adalah alat yang kuat untuk menangkap pemikiran dalam bentuk yang mudah dibaca, dan memungkinkannya dikelola dengan version control seperti teks lainnya

  • Begitu sistem mulai berubah, diagram yang cantik menjadi sangat sulit dipelihara. Bayangkan menambahkan kotak baru di tengah diagram yang sudah rumit; bisa saja butuh satu jam untuk merapikan ulang semuanya
    Waktu developer di era 2020-an mungkin lebih baik dipakai untuk mengelola diagram sebagai kode: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • Saya selalu bercanda bahwa 10% pekerjaan membuat diagram adalah benar-benar membuat diagram, dan 90%-nya adalah menyelaraskan panah
      Tapi rasanya itu sebenarnya bukan sekadar lelucon
    • Saya pernah memelihara model C4 untuk diimpor dan ditampilkan di structurizr.com, dan jujur saja itu tidak menyenangkan. Kode saja tidak memberi pemahaman intuitif dan gambaran menyeluruh yang didapat dari diagram, dan tidak ada pratinjau lokal yang cepat, sehingga kodenya harus diunggah ke server
      Yang lebih buruk, saat menambahkan kotak baru, biasanya semua panah harus disejajarkan ulang. Akibatnya, diagram tidak terus-menerus terjaga tetap mutakhir
      Untuk sequence diagram, pengalaman saya lebih baik saat memakai plantML. Pekerjaannya sendiri lebih mudah, sehingga output interpreter biasanya sudah layak dipakai tanpa intervensi manual
    • Artikel itu juga membahas bahwa mengubah diagram memakan banyak waktu. Dalam praktiknya memang benar begitu, dan akan bagus kalau kita bisa mengikuti skema standar dengan benar dan alatnya menyediakan opsi pemformatan otomatis
    • Saat memindahkan dan merapikan ulang elemen, kita harus mempelajari ulang seluruh diagram. Jika frobnitz yang selalu berada di kanan atas tiba-tiba dipindah ke tengah kiri karena lebih baik dari sisi perataan, bagi orang yang baru melihat mungkin membantu, tetapi bagi orang yang sudah melihatnya selama 6 bulan, itu tampak seperti benda yang sama sekali berbeda
      Mirip dengan UI yang jelek. Meski jelek, para penggunanya sudah terbiasa. Saat Anda “merapikannya”, Anda justru merusak model mental mereka dan memaksa mereka belajar lagi
    • Apakah investasi waktu itu sepadan bergantung pada jangkauan dan umur diagramnya
      Kadang Anda hanya membuat sketsa untuk merapikan pikiran, yang akan dibuang 20 menit kemudian
      Tetapi jika itu adalah materi referensi untuk onboarding atau menjelaskan sistem kepada tim lain, satu jam yang dipakai untuk membuatnya lebih mudah dipahami bisa sangat terbayar

  • Untuk menggambar hal seperti ini, saya memakai yEd. Meski kotak dan panah dibuat berantakan, beberapa klik di menu bisa merapikannya secara otomatis
    Namun tetap perlu kompromi. Kotak di dalam kotak tidak selalu berakhir baik. Meski begitu, dokumentasi bisa dibuat jauh lebih cepat, dan setelah beberapa kali mencoba, Anda akan mulai paham apa yang berhasil dan tidak, jadi bagi saya ini kompromi yang cukup baik

    • Saya penasaran apakah yEd bisa dipakai gratis. yWorks SDK yang menjadi dasarnya tampaknya menelan biaya nominal 5 digit bahkan untuk satu developer di satu situs web. Kalau mereka punya pelanggan selama hampir 20 tahun, alat itu pasti cukup kuat
    • Saya juga memakainya dengan cara yang sama. Tidak ada alasan menggambar sendiri
      Cukup ekstrak relasinya sebagai TGF, impor, lalu terapkan layout hierarkis
      Format from, to, relation sudah cukup
    • Untuk alasan serupa, saya memakai OmniGraffle

  • Ini punya kemiripan kuat dengan skema listrik, diagram rangkaian, dan gambar teknik lainnya. Tidak ada satu cara yang “benar”
    Seperti halnya kode, kemampuan memilih abstraksi dan cara representasi yang baik menjadi pembeda antara ide yang bisa dipahami dan kekacauan yang disesali. Ini bukan soal keindahan atau estetika, melainkan alat yang menuntut pemikiran dan upaya aktif dalam perancangan

    • Menjaga tingkat abstraksi tetap konsisten kadang benar-benar sulit. Khususnya pada diagram infrastruktur, sulit menahan dorongan untuk memasukkan lebih banyak detail pada tingkat yang berbeda-beda
      Akan menyenangkan kalau ada alat yang memungkinkan kita memperbesar masuk ke dalam diagram dengan mudah, seperti animasi zoom tak terbatas

  • https://VisualFlows.io v1.0 akan segera dirilis
    Dalam beberapa menit, saya bisa membuat peta “arsitektur” animasi untuk SaaS perusahaan induk: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    Fitur utamanya mencakup Smart Sections, Smart Edges, Smart Node Deletion, mode gelap/terang, embed, drag-and-drop gambar/SVG/GIF, ikon AWS/Windows/Google, serta Markdown yang dijadwalkan minggu depan
    Lihat Smart Sections: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • Saya penasaran apa alasan untuk memakai ini dibanding https://whimsical.com yang lebih matang dan punya estetika serupa

  • Saya sangat menyukai tulisan ini. Saat menggambar diagram arsitektur, menulis dokumen atau kode, atau melakukan sesuatu di pekerjaan, saya mencoba meluangkan sedikit waktu untuk membuatnya “enak dilihat”
    Sulit menjelaskan alasannya, tapi saya tahu setelah melihatnya saya jadi lebih menyukainya
    Saya sempat agak khawatir itu mungkin bukan cara terbaik menggunakan waktu, tetapi saya belum pernah mendengar orang mengatakan jangan melakukannya
    Alasan tulisan ini bagus adalah karena ia menjelaskan sesuatu yang sebelumnya dilakukan berdasarkan intuisi sebagai cara praktis untuk membuat sesuatu lebih indah

    • Saya juga melakukannya seperti ini. Coding bagi saya adalah pekerjaan yang cukup visual. Sulit dijelaskan selain sebagai “alur”. Kalau kode tidak punya alur, rasanya tidak memuaskan
      Saya bingung melihat rekan tim yang tampaknya tidak punya kepekaan visual terhadap kode. Misalnya tidak memberi baris kosong antara akhir fungsi dan deklarasi fungsi berikutnya, atau tidak konsisten: kadang menulis parameter pada signature fungsi satu per baris, kadang beberapa sekaligus dalam satu baris. Bagi mata saya itu sangat mencolok, tetapi mereka tampaknya tidak peduli
    • Meski tidak dibagikan kepada siapa pun, proses memikirkan urutan blok dan elemen di halaman itu sendiri membuat kita memikirkan struktur yang lebih besar dan dependensinya. Itu sangat membantu
    • Saya merasakan hal yang sama saat membuat diagram jaringan dengan Visio. Saya masuk ke mode Steve Jobs dan terobsesi pada detail-detail kecil
      Kadang memang memakan waktu, tapi ada rasa terpenuhi. Saya tahu saya punya sedikit bakat seni teknis, dan saat SMA saya ingin menjadi drafter
    • Karena itulah markup ada. Ia membantu kita lepas dari dekorasi yang tidak produktif. Tentu saja ini tidak berlaku untuk coding
    • “Diskusi berputar di sekitar diagram ini. Orang-orang tanpa sadar mendekat dan memandanginya. Pertanyaan dijawab dengan menunjuk diagram. Secara berkala sepanjang hari, kursi diputar menghadap objek pusat ini, dan orang-orang menautkan tangan di belakang kepala.”
      Itulah tujuan visualisasi itu sendiri

  • D2 bagus untuk penggunaan seperti ini. Di peran sebelumnya, saya menulis program yang mem-parsing semua file serverless.yml dan otomatis menghasilkan diagram D2 raksasa
    Kami menjalankan microservices di AWS, dan bagus karena diagram itu otomatis diperbarui saat sistem membesar. Saya membuatnya bisa dipecah menjadi diagram-diagram kecil untuk tiap subsistem, misalnya dipisahkan berdasarkan SNS topic

    • Saya juga suka draw.io

  • Saya tidak memahami contoh pertama. Penulis membahas node yang tidak direncanakan, lalu benar-benar menamainya “I was unplanned”, dan mengatakan “jika sudah direncanakan sebelumnya”
    Dalam konteks diagram, saya tidak tahu bagaimana sesuatu yang tidak direncanakan bisa direncanakan sebelumnya. Saya bertanya-tanya apakah maksudnya kita harus menyisakan ruang kosong yang cukup di sekitar semua node
    Selain itu, usulan perbaikannya membuat “something” dan “I was unplanned” tampak memakai kanal atau mekanisme yang sama saat berinteraksi dengan “engine”

  • Saya memakai Miro, dan untuk hal tingkat tinggi atau brainstorming ide, tool sticky note-nya cukup bagus. Namun tidak lebih dari level menengah
    Setelah komponen dan sistemnya ditentukan, ada tool lain yang lebih cocok untuk pekerjaan itu

  • Jika dokumentasi proyek ditulis dalam Markdown, Anda bisa menyisipkan diagram dengan memasukkan blok ```plantuml, bukan binary terpisah
    Di GitLab, ini dirender dengan rapi saat melihat file .md lewat browser. GitHub belum punya fitur itu