Eskimeyen Mimari Diyagramlar: Yaşayan Dokümantasyon İş Akışı

Her mühendislik organizasyonunda bir tane vardır: wiki'deki, yıllar önce birkaç hafta boyunca doğru olan mimari diyagram. Yeni katılan biri onu inceler, sonra bir meslektaşından kutuların yarısının yeniden adlandırıldığını ve ortadaki kuyruğun geçen bahar değiştirildiğini öğrenir. Mimari dokümantasyon en iyi uygulamalarının çoğu neyin çizileceğine odaklanır. Bu yazı daha zor olan kısımla ilgili: diyagramları ilk taslaktan sonra da doğru tutmak ve onları tek seferlik çıktılar yerine yaşayan dokümanlar olarak ele alan bir iş akışı kurmak.

Mimari dokümanlar neden eskir?

Diyagramlar insanlar tembel olduğu için nadiren eskir. Eskirler, çünkü etraflarındaki süreç eskimeyi varsayılan hâle getirir.

• Tek seferlik çıktılardır. Bir diyagram bir tasarım incelemesi, bir migrasyon başlangıcı ya da bir denetim için çizilir. Toplantı bittiğinde kimsenin onu tekrar açması için bir sebep kalmaz.
• Ekran görüntüleri her yere yapıştırılır. Kaynak dosya birinin dizüstü bilgisayarında durur; bir PNG ise wiki'ye, onboarding dokümanına, üç sunuma ve bir README'ye girer. Artık beş kopya vardır ve hiçbiri düzenlenemez.
• Sahipleri yoktur. “Platform ekibi” bir sahip değildir. Belirli biri sorumlu olmadığında herkes güncellemeyi başkasının yapacağını varsayar.
• Güncellemeyi hiçbir şey tetiklemez. Kod değişiklikleri pull request, inceleme ve CI'dan geçer. Diyagramlar ise yalnızca biri hatırladığında değişir; bu da nadiren sistemin değiştiği andır.
• Fazla şey gösterirler. Her Pod'u, her kuyruğu, her IAM rolünü ve her kullanıcı yolculuğunu içeren bir diyagram, bittiği gün eskimiştir; çünkü herhangi bir yerdeki herhangi bir değişiklik onu yanlış yapar.

Bunların hiçbiri öncelikle araç sorunu değildir; daha iyi bir çizim aracı eksik bir sahibi telafi etmez. Ama araç, doğru iş akışını ucuz ya da pahalı hâle getirebilir.

Yaşayan diyagramlar için mimari dokümantasyon en iyi uygulamaları

Önerdiğimiz iş akışı aşağıda. Bilerek net görüşlü.

1. Her diyagram için tek doğruluk kaynağı

Her diyagram tam olarak tek bir düzenlenebilir yerde bulunur. Geri kalan her şey o yere işaret eden bir bağlantı ya da embed'dir. Bir yere yapıştırmak için PNG dışa aktarmak üzereyseniz, bir bağlantının yetip yetmeyeceğini sorun. Genellikle yeter.

2. Kopyalamayın, bağlantı verin

Wiki'ler, doküman siteleri ve README'ler canlı diyagrama işaret etmeli, onun bir resmini içermemelidir. Gömülü canlı bir diyagram, kaynak değiştiğinde değişir; yapıştırılmış bir ekran görüntüsü ise bir sonraki değişiklikten sonra sonsuza dek yanlıştır. Bir denetçi için PDF gibi statik bir görsele gerçekten ihtiyacınız olduğunda, onu tarihli bir dışa aktarım olarak ele alın ve insanların günlük olarak güvendiği dokümanların dışında tutun.

3. Bir sahip belirleyin

Her diyagramın bir sahibi olur: bir kişi ya da adı belli bir irtibat kişisi olan bir ekip. Sahip her değişikliği kendisi çizmez, ama diyagram yanlış olduğunda bunu fark eden ve soruların yöneltildiği kişidir. Sahibi diyagramın üzerine ve diyagram indeksinize yazın.

4. Güncelleme tetikleyicilerini zaten var olan olaylara bağlayın

Hafızaya güvenmeyin. Diyagram güncellemelerini zaten gerçekleşen olaylara bağlayın:

• Pull request'ler. PR şablonuna bir mimari etki onay kutusu ekleyin.
• ADR'ler. Kabul edilen her mimari karar kaydı (ADR) değiştirdiği diyagrama bağlantı verir ve diyagram, kararın kabulünün bir parçası olarak güncellenir.
• Olay sonrası analizler (postmortem). Olay, diyagramın yanlış olduğunu ya da bir bağımlılığı atladığını gösterdiyse, düzeltmek bir aksiyon maddesi olur.
• Üç aylık gözden geçirme. Sahipler her diyagram için birkaç dakika ayırıp gerçeklikle hâlâ örtüştüğünü doğrular, ardından “son gözden geçirme” tarihini günceller.

Bir PR şablonu parçası:

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. Doğru detay seviyesini seçin

Tek bir dev resim yerine seviyeler kullanın. C4 model size ortak bir dil sunar: System Context görünümü (kişiler ve sistemler), Container görünümü (uygulamalar ve veri depoları) ve tek bir container içindeki Component görünümü. Üst seviyeler nadiren değişir ve doğru tutulması ucuzdur. Alt seviyeler sık değişir; bu yüzden onları yalnızca insanların ihtiyaç duyduğu yerlerde çizin ve bunun altında doğruluk kaynağı kod olsun.

İşe yarar bir kural: Bir diyagram her sprintte değişiyorsa, muhtemelen bir seviye fazla derin çizilmiştir.

6. Tarihi ve sürümü görünür kılın

Her diyagramın bir köşesine sahibi ve “son gözden geçirme” tarihini koyun. Okuyucular güvenilirliği bir bakışta değerlendirebilir: Geçen ay gözden geçirilmiş bir diyagram ile iki yıl önce gözden geçirilmiş bir diyagram farklı düzeyde güveni hak eder. Tarih olmadığında her diyagram eşit derecede yetkili görünür; bu, eski bir tarihi göstermekten daha kötüdür.

7. Bir diyagram indeksi tutun

Tek bir sayfa, önemli olan tüm diyagramları listeler:

İndeks boşlukları (sahibi olmayan, tarihi eski diyagramlar) görünür kılar ve üç aylık gözden geçirme için doğal başlangıç noktasıdır.

8. Diyagramları ADR'lerle eşleştirin

Bir diyagram mimarinin ne olduğunu gösterir. Neden öyle olduğunu gösteremez. Mimari karar kayıtları bu boşluğu doldurur. Michael Nygard'ın orijinal ADR formatı insanların gerçekten yazacağı kadar kısadır: başlık, durum, bağlam, karar, sonuçlar. ADR'den diyagrama, diyagramdan da ADR'ye bağlantı verin:

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

Altı ay sonra biri “Bu neden böyle?” diye sorduğunda, cevap bir tık uzaklıkta olur.

Archboard yaşayan doküman iş akışını nasıl destekler?

Archboard barındırılan (hosted) bir mimari çalışma alanıdır ve yukarıdaki iş akışının çoğu zaten sunduğu özelliklere karşılık gelir. Neleri karşıladığı ve nerede hâlâ kendi sürecinize ihtiyaç duyduğunuz aşağıda.

• Tek doğruluk kaynağı. Her diyagram, çalışma alanınızda otomatik kayıt ve revizyon anlık görüntüleri olan tek bir dokümandır. Free son 5 revizyonu saklar; Pro bir yıllık revizyon geçmişi tutar, Enterprise'da sınır yoktur.
• Kopyalamayın, bağlantı verin. Her planda herkese açık paylaşım bağlantısı vardır (Free'de markalı). Pro ve Enterprise'da bir diyagramı iframe ile doküman sitenize gömebilirsiniz; böylece sayfa, zamanla eskiyen bir ekran görüntüsü yerine güncel sürümü gösterir.
• Depoda geçmiş. Diyagramı yapılandırılmış JSON olarak dışa aktarın ve kodun ya da ADR'lerinizin yanına commit edin. Böylece uygulama içi revizyonların yanında Git geçmişi ve diyagram değişiklikleri için bir inceleme adımı elde edersiniz. Dışa aktarım manuel bir adımdır; bu yüzden onu PR alışkanlığınızın parçası yapın.
• Canvas üzerinde notlar. Markdown node'ları canvas'ın üzerinde durur; böylece sahip, “son gözden geçirme” tarihi, ADR bağlantıları ve kısa bir lejant ayrı bir dokümanda değil, diyagramın içinde yer alır.
• Doğru detay seviyesi. C4 Model paketinde Person, Software System, Container, Component ve Database node'ları ile boundary'ler bulunur. Node'lar portları olan birinci sınıf node'lardır ve onları portları birbirine bağlayarak bağlarsınız. Context ve container görünümlerini ayrı diyagramlar olarak tutun.

Tek bir sistem için somut bir kurulum:

1. İki diyagram oluşturun: “Payments: Context” ve “Payments: Containers”.
2. Sol üst köşeye sahibi, son gözden geçirme tarihini ve ilgili ADR bağlantılarını içeren bir Markdown node'u ekleyin.
3. Pro'da container görünümünü servisin doküman sayfasına gömün. Free'de paylaşım bağlantısını kullanın.
4. Bir PR mimariyi değiştirdiğinde diyagramı güncelleyin (ya da bunu PR üzerinde çalışan kodlama ajanına Archboard'un MCP sunucusu üzerinden yaptırın), JSON'u dışa aktarın ve aynı PR içinde docs/architecture/ klasörüne commit edin.
5. Her iki diyagramı da indeks sayfanıza ekleyin.

Tüm özellikler için ürün genel bakışına, C4'e özel kurulumlar için C4 kullanım senaryosuna, her planın neleri içerdiği için de fiyatlandırma sayfasına bakın. Free, bir sistemin context görünümünü denemeniz için her biri 15 diyagram node'u + 150 not, metin, çıkartma ve zihin haritası konusu alan 3 diyagram sunar; tüm platformu belgelemeye geçtiğinizde Pro sınırsız diyagram ve node açar.

Yaşayan doküman kontrol listesi

• Her diyagramın tam olarak tek bir düzenlenebilir kaynağı var
• Dokümanlar canlı diyagramı gömüyor ya da ona bağlantı veriyor; yapıştırılmış ekran görüntüsü yok
• Her diyagramın adı belli bir sahibi var ve bu sahip diyagramda gösteriliyor
• PR şablonunda mimari etki onay kutusu var
• Kabul edilen ADR'ler değiştirdikleri diyagramlara bağlantı veriyor
• Postmortem'lerde “Diyagram hâlâ doğru mu?” sorusu soruluyor
• Sahipler diyagramlarını üç ayda bir gözden geçirip tarihi güncelliyor
• Diyagramlar tek dev resim yerine C4 seviyelerine ayrılmış
• Bir diyagram indeksi seviye, sahip, son gözden geçirme tarihi ve ADR'leri listeliyor
• Diyagram kaynağı (örneğin JSON dışa aktarımı) kodun yanına commit ediliyor

SSS

Bir sistemin kaç diyagramı olmalı? Bir context ve bir container görünümüyle başlayın. Component görünümlerini yalnızca insanların düzenli olarak sorduğu kısımlar için ekleyin. Birkaç doğru diyagram, çok sayıda eskimiş diyagramdan iyidir.

Diyagramlar depoda mı yoksa bir araçta mı durmalı? Tek bir yerde düzenleyin ve geçmişi ekibinizin değişiklikleri zaten incelediği yerde tutun. Archboard'da canvas üzerinde düzenler, JSON dışa aktarımını Git'e commit edersiniz.

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