Canlı Mimari Diyagramları Dokümantasyona, Notion'a, Confluence'a ve GitHub'a Gömme

Wikiye ekran görüntüsü olarak giren her mimari diyagram, yavaş bir geri sayım başlatır. Sistem değişir, biri kaynağı günceller; onboarding rehberindeki, runbook'taki ve tasarım dokümanındaki ekran görüntüsü ise olduğu gibi kalır. Altı ay sonra hiçbirine kimse güvenmez.

Çözümü söylemesi kolay: tek bir canlı diyagram tutun ve her sayfayı ona yönlendirin. Bu rehber, nasıl yapılacağını her ortam için tek tek anlatıyor: doküman siteleri, Notion, Confluence, GitHub README'leri ve sohbet araçları; ayrıca bir sayfanın canlı diyagram gösteremediği yerlerde ne yapılacağını da ele alıyor. Daha geniş iş akışı için Eskimeyen mimari diyagramlar yazısına bakın.

Bir diyagramı göstermenin üç yolu

Mümkün olduğunda ilk ikisini kullanın; dışa aktarmaya yalnızca canlı hiçbir şeye izin verilmeyen yerlerde başvurun.

Bağlantıyı ve gömme kodunu alın

Archboard'da diyagramı açın ve Paylaş'a tıklayın:

1. Bağlantıya sahip herkes seçeneğini açın ve paylaşım bağlantısını kopyalayın. İzleyiciler diyagramı hesap açmadan canlı izler ve düzenleyemez.
2. Pro planında Göm seçeneğini açın ve gömme kodunu kopyalayın. Kod şöyle görünür:

<iframe src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN" width="100%" height="480" style="border:0;border-radius:8px;" allowfullscreen loading="lazy" title="Archboard diagram"></iframe>

Bağlantıyı ya da gömme kodunu istediğiniz zaman yenileyebilirsiniz; bu durumda eskisi artık çalışmaz. Paylaşımı da kapatabilirsiniz; o zaman izleyicilerin bağlantısı hemen kesilir.

Canlı bir diyagramı herkese açık bir sayfaya koymadan önce bilmeniz gereken bir şey var: izleyiciler düzenlemeleri anında görür; düzenleme yetkisiyle diyagramı editörde açık tutan kişilerin ve üzerinde çalışan AI ajanlarının adlarını ve imleçlerini de görür. İzleyicilerin kendi adları ise hiçbir zaman gösterilmez.

Doküman siteleri

Düz HTML, Jekyll, MkDocs ve çoğu statik site üreticisi. Gömme kodunu diyagramın görüneceği yere yapıştırın; bu araçlarda Markdown içinde ham HTML kullanılabilir. Hugo ise Markdown içindeki ham HTML kodunu varsayılan olarak çıktıya almaz; bu yüzden iframe'i bir shortcode'a koyun ya da site yapılandırmasında markup.goldmark.renderer.unsafe = true ayarını yapın.

Docusaurus ve diğer MDX siteleri. MDX, JSX bekler; bu yüzden style özniteliği bir nesne olmalı, öznitelik adları da camelCase yazılmalıdır:

<iframe
  src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN"
  width="100%"
  height="480"
  style={{ border: 0, borderRadius: 8 }}
  allowFullScreen
  loading="lazy"
  title="Checkout service architecture"
/>

Okuyucular için iki küçük alışkanlık işe yarar: diyagramı kaydırma gerektirmeden sığdıran bir yükseklik belirleyin ve her iframe'e diyagramı anlatan bir title verin; ekran okuyucular bu başlığı seslendirir.

Notion

/embed yazın, Embed bloğunu seçin ve gömme kodundaki src özniteliğinin URL'sini yapıştırın (iframe etiketinin tamamını değil). Notion gömülü içerikleri kendi gömme servisi üzerinden yükler; bir sayfa doğrudan gösterilemiyorsa Notion onun yerine bir hata görüntüler. Bu durumda paylaşım bağlantısını yer imi olarak yapıştırın: tek tıkla canlı diyagram açılır.

Confluence

Confluence Cloud, editörde ham HTML ya da iframe kodu kabul etmez. Paylaşım bağlantısını yapıştırın; Confluence onu bir bağlantıya ya da karta dönüştürür. Kuruluşunuz Marketplace uygulamalarına izin veriyorsa, bir iframe ya da HTML makrosu uygulaması gömülü diyagramı sayfanın içinde gösterebilir.

Confluence Data Center'da yöneticilerin etkinleştirebileceği bir HTML makrosu vardır. Bu makro, düzenleme yetkisi olan herkesin sayfalara istediği HTML ve JavaScript kodunu eklemesine olanak tanıdığı için birçok kuruluş onu kapalı tutar. Planınızı buna dayandırmadan önce yöneticinize danışın.

GitHub README'leri ve depolardaki Markdown

GitHub, Markdown içindeki iframe'leri render etmez; bu nedenle README'de canlı gömme mümkün değildir. En iyi alternatif, kodun yanına commit edilen ve canlı diyagrama bağlantı veren, dışa aktarılmış bir SVG'dir:

[![Checkout architecture](docs/architecture.svg)](https://getarchboard.app/s/YOUR_SHARE_TOKEN)

Okuyucular resmi README'de görür, tıklayınca da güncel sürüm açılır. Pull request şablonunuza "Diyagram dışa aktarımı güncellendi mi?" maddesini ekleyin; diyagram değişikliklerinin veri olarak incelenmesini istiyorsanız JSON dışa aktarımını da commit edin.

Slack, Teams, Jira ve e-posta

Paylaşım bağlantısını yapıştırın. Bağlantı her zaman güncel sürümü açar; böylece bir thread'deki eski mesaj eski bir resme işaret etmez.

Düzeni ayakta tutan pratikler

• Tek diyagram, çok bağlantı. "Wiki için bir sürüm hazırlamak" amacıyla bir diyagramı asla ikinci bir dosyaya kopyalamayın.
• Başlığı, sahibini ve son inceleme tarihini tuvale yazın. Gömmeler ve bağlantılar sayfanızın meta verilerini değil, tuvali gösterir.
• Bilinçli paylaşın. Herkese açık bir sayfadaki bağlantı ya da gömme, diyagramı herkese açık hale getirir. İç mimariyi iç sayfalarda tutun; bağlantı sızarsa onu yenileyin.
• Dışa aktarmayı alışkanlık değil, yedek çözüm olarak kullanın. Her dışa aktarım, eskiyebilecek bir kopyadır.

Kurulumun tamamı tek bir tuvalde:

Archboard'da oluşturun

Herhangi bir diyagramı açın, Paylaş'a tıklayın ve bağlantıyı açın; Pro planındaysanız gömmeyi de açın. Dokümanlarınız için yeni bir diyagrama başlıyorsanız şablonlar ve örnekler hızlı bir başlangıç sağlar. Yukarıdaki diyagram Temel paketinden dokuz kutu kullanıyor ve Free planın sınırları içinde kalıyor.

SSS

Free planda diyagram gömebilir miyim? Free planda markalı paylaşım bağlantısı vardır. Gömme (iframe) ise Pro ve Enterprise planlarına dahildir.

İzleyicilerin hesabı olması gerekir mi? Hayır. Bağlantıya sahip olan ya da gömmenin bulunduğu sayfayı açan herkes diyagramı canlı görüntüleyebilir. Diyagramı düzenleyemezler.

Paylaşımı sonradan durdurabilir miyim? Evet. Eskisini geçersiz kılmak için bağlantıyı ya da gömme kodunu yenileyin veya izleyicilerin bağlantısını hemen kesmek için paylaşımı kapatın.

Dışa aktarılan SVG, diyagram değişince güncellenir mi? Hayır. Dışa aktarımlar kopyadır. Diyagram değiştiğinde yeniden dışa aktarın ya da mümkün olan her yerde bağlantı veya gömme kullanın.

Gömdüğüm diyagram Notion'da ya da Confluence'ta neden hata veriyor? İki araç da neyin gömülebileceğini kendisi denetler. Bunun yerine paylaşım bağlantısını yer imi ya da kart olarak kullanın veya gömme uygulamaları için yöneticinize danışın.

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