Mermaid mi, diyagram tuvali mi? Kod olarak diyagram ne zaman işe yarar, ne zaman yaramaz

Mühendislik ekiplerinde bu kadar uzun süren araç tartışması azdır. Kimileri her diyagramın kod olarak, Mermaid ile yazılmasını ve pull request'lerde incelenmesini ister. Kimileri ise kutuları istedikleri gibi taşıyıp sistemi görebilecekleri bir tuval ister. İki taraf da haklı, ama farklı diyagramlar için.

Bu rehber Mermaid'i ve bir diyagram tuvalini dürüstçe karşılaştırıyor: her birinin neyi iyi yaptığı, nerede yetersiz kaldığı, sık karşılaşılan durumlar için bir karar tablosu ve aynı küçük sistemin iki şekilde çizimi.

Mermaid'in iyi yaptıkları

Mermaid birkaç satırlık metni bir diyagrama dönüştürür. Bunun gerçek avantajları var:

• Kodun yanında yaşar. Markdown dosyasındaki bir diyagram, anlattığı kodla aynı pull request'te değişir ve inceleyenler diff'i görür.
• Mühendislerin zaten çalıştığı yerde görüntülenir. GitHub ve GitLab, Markdown dosyalarındaki, issue'lardaki ve pull request'lerdeki Mermaid kod bloklarını render eder; Notion ve Obsidian gibi araçlar da bu blokları gösterir.
• Ek araç ya da hesap gerekmez. Dosyayı düzenleyebilen herkes diyagramı da düzenleyebilir.
• Sequence diyagramlarında mükemmeldir. Dört servis arasındaki bir istek akışı için Mermaid'in sequence sözdizimini geçmek zordur.
• AI asistanları onu akıcı biçimde yazar. Herhangi bir sohbet asistanından Mermaid akış şeması isteyin, çoğu zaman geçerli bir sözdizimi alırsınız.

Mermaid'in zorlandığı yerler

• Yerleşimi siz kontrol etmezsiniz. Mermaid düğümleri otomatik yerleştirir. Tek bir kenar ekleyin, resmin tamamı yeniden dizilebilir; birkaç düzine düğümden sonra da okunması zorlaşır.
• Metin diff'leri görsel değişiklikleri gizler. Pull request'teki tek satırlık bir değişiklik diyagramın yarısını yerinden oynatabilir; inceleyenler ise yalnızca o satırı görür.
• Altyapı için kelime dağarcığı zayıftır. Akış şeması şekilleri geneldir. Daha yeni mimari ve C4 diyagram türleri var, ama akış şemaları ve sequence diyagramları kadar olgun değiller.
• Mühendis olmayanlar nadiren düzenler. Ürün yöneticileri, tasarımcılar ve destek ekipleri sonucu okuyabilir, ama kaynağı genellikle değiştirmez.
• Ortak, canlı bir oturum yoktur. Metni kendi editörünüzde düzenlersiniz; imleç yok, canlı inceleme yok, bir değişikliğin gelişini izleyen kimse yok.

Tuvalin iyi yaptıkları

• Yerleşim sizin elinizdedir. Konum anlam taşır: bir güven sınırının nereden geçtiği, bir isteğin soldan sağa akışı, ortadaki küme.
• Tipli düğümler ve çerçeveler. Archboard gibi bir tuvalde bir Kubernetes Service'i ya da bir C4 konteyneri, portları olan bir düğümdür; namespace'ler ya da VPC'ler ise içeriklerini barındıran çerçevelerdir.
• Herkes düzenleyebilir. Repoyu hiç açmayan kişiler bile bir etiketi düzeltebilir ya da not ekleyebilir.
• Canlı iş birliği ve paylaşım. Birden çok kişi ve AI ajanları imleçleriyle birlikte düzenler; canlı bir bağlantı ya da gömme, her okuru güncel sürümde tutar.

Tuvalin zorlandığı yerler

• Güncellemeyi iş akışınıza katmazsanız koddan kopar. Tuval varsayılan olarak pull request'te yer almaz.
• Bazı biçimler kapalı kutudur. Bir PNG'yi ya da tescilli biçimdeki bir dosyayı ne diff'leyebilir ne de otomatik üretebilirsiniz. Archboard bunu JSON dışa aktarma ve yayımlanmış bir JSON Schema ile hafifletir; yine de bir JSON belgesi on satırlık bir Markdown bloğu değildir.
• Bir araç gerektirir. Okurlar bir paylaşım bağlantısını hesap olmadan görüntüleyebilir, ama düzenleyenlerin hesaba ihtiyacı vardır.

Karar tablosu

Örüntü şu: Diyagram tek bir değişikliğe aitse ve kodda yaşıyorsa Mermaid kazanır. Diyagram ekibe aitse ve tek tek değişikliklerden daha uzun ömürlüyse tuval kazanır.

Aynı sistem, iki şekilde

Mermaid ile yazılmış küçük bir sistem:

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

Okunaklıdır, diff'leri temiz çıkar ve GitHub onu render eder. Şimdi aynı akış şemasını bir tuvalde görelim. Şemayı, MCP üzerinden Archboard'a bağlı bir AI ajanına, Mermaid id'lerini düğüm türlerine eşleyen bir listeyle birlikte verdik: user bir C4 Kişi düğümüne, web, api ve worker C4 Konteyner düğümlerine, db Postgres'e, q bir Konu (topic) düğümüne, mail de bir Harici sistem düğümüne. Ajan diyagramı tek adımda çizdi, ikinci bir adımda da iki sıraya dizdi:

Subgraph bir çerçeveye, düğümler de portları olan tipli düğümlere dönüştü. Ortaya çıkan sonuç, artık diğer diyagramlar gibi yerleşimini düzenleyebileceğiniz, açıklama ekleyebileceğiniz ve paylaşabileceğiniz bir başlangıç noktası.

İkisini de bilinçli kullanın

Çoğu ekip için işe yarayan bir ayrım:

1. Bir değişikliğe ait diyagramlar için Mermaid: tasarım dokümanlarında ve pull request'lerde sequence diyagramları, kodun yanında durum makineleri, README'lerde küçük akış şemaları.
2. Ekibe ait diyagramlar için tuval: sistem genel görünümleri, altyapı, güvenlik incelemeleri, onboarding.
3. İkisini birbirine bağlayın. Elinizde Mermaid varsa oradan başlayın: MCP üzerinden Archboard'a bağlı bir ajan, bir Mermaid akış şemasını gerçek düğüm türleriyle bir tuval diyagramına dönüştürebilir. Kodla birlikte incelenmesini istediğinizde tuvali JSON olarak dışa aktarıp repoya ekleyin ve README'den canlı diyagrama bağlantı verin.

SSS

Mermaid'i Archboard editörüne yapıştırabilir miyim? Şu an doğrudan değil. MCP üzerinden bağlı bir AI ajanı, subgraph'ler dahil bir Mermaid akış şemasını gerçek düğüm türleriyle bir tuval diyagramı olarak çizebilir. Sequence diyagramları gibi diğer Mermaid diyagram türleri dönüştürülmez.

Bir tuval diyagramı pull request'lerde görünür mü? Kendiliğinden görünmez. Kodla birlikte incelenmesini istiyorsanız JSON ya da SVG olarak dışa aktarıp repoya ekleyin veya pull request'ten canlı diyagrama bağlantı verin.

Kod olarak diyagram her zaman daha mı güncel? Yalnızca birileri güncellerse. Kimsenin dokunmadığı bir Mermaid bloğu da bir tuval kadar hızlı eskir; fark, onu güncellemesi gereken değişikliğe daha yakın durmasıdır.

PlantUML ya da Structurizr ne olacak? Artıları ve eksileri aynı. PlantUML, UML ve sequence diyagramlarında güçlüdür; Structurizr ise C4 modellerini kod olarak yazmak için tasarlanmıştır. Seçimi, diyagramı kimin düzenleyeceğine ve ne kadar yaşaması gerektiğine göre yapın.

AI asistanları hangisiyle daha iyi başa çıkar? İkisiyle de. Asistanlar Mermaid'i akıcı yazar; MCP üzerinden bir ajan tuvali doğrudan da düzenleyebilir ve insanlar değişikliği orada canlı görüp geri alabilir.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.