Dokümantasyon Borcu: Diyagramlar Neden Güncelliğini Kaybeder ve Bunu Nasıl Önleyebiliriz?

Dokümantasyon Borcu: Diyagramlar Neden Güncelliğini Kaybeder ve Bunu Nasıl Önleyebiliriz?

SharePoint sayfasındaki mimari diyagramı 2009 yılında oluşturuldu. O zamanlar doğruydu, büyük bir platform geçişi sırasında sistemin mevcut halini yansıtıyordu ve her bileşeni ve ilişkilerini belgelemek için üç hafta harcayan bir mimar tarafından çizilmişti. 2009'dan beri sistem yaklaşık 4,800 commit aldı, on beş ekip katkıda bulundu, diyagramda gösterilen bileşenlerden dördü artık mevcut değil, on bir yeni bileşen eklendi ve hiç diyagrama dahil edilmedi ve diyagramı çizen mimar 2016'da emekli oldu. Diyagram hala mevcut. Yeni bir geliştirici katıldığında ve "sistem nasıl çalışıyor?" diye sorduğunda, birisi onlara SharePoint bağlantısını gönderiyor. Diyagram bir dokümantasyon değil, bir arkeoloji.

Dokümantasyon borcu, dokümantasyon katmanına uygulanan teknik borçtur: dokümantasyonun bir sistem hakkında söyledikleri ile sistemin gerçekte yaptıkları arasındaki birikmiş fark. Diyagramların tasvir ettikleri sistemlerden kopması anlamına gelen mimari kayma, hem en yaygın hem de en tehlikeli dokümantasyon borcu biçimidir. En tehlikeli olmasının nedeni, yanlış bir güven duygusu yaratmasıdır: var olan ve profesyonel görünen bir diyagram, paydaşlara sistemin anlaşıldığı izlenimini verirken, aslında gördükleri şey, gösterilen biçimde artık var olmayan bir sistemi tanımlayan tarihsel bir kalıntıdır. Güncelliğini yitirmiş diyagramlar, hiç diyagram olmamasından daha kötüdür çünkü hiç diyagram olmaması insanları gerçekte neyin var olduğunu bulmaya yönlendirirken; güncelliğini yitirmiş diyagramlar insanları artık doğru olmayan şeylere göre hareket etmeye yönlendirir.

Zahmetsiz Belgeleme

SMART TS XL Önceki analiz çalışmasından bu yana yapılan her program, bağımlılık ve copybook değişikliğinin bir değişiklik günlüğünü oluşturur.

DAHA FAZLASINI ÖĞRENİN…

Diyagramların Eskimesine Yol Açan Beş Mekanizma

Dokümantasyon kaymasıyla ilgili her makalede "diyagramlar zamanla güncelliğini yitirir" denir. Ancak neredeyse hiçbiri bunun hangi mekanizmalarla gerçekleştiğini açıklamaz. Bu mekanizmaları anlamak, onları önlemenin ön koşuludur, çünkü farklı mekanizmalar farklı önleme stratejileri gerektirir.

1. Biriken delta problemi. Bir diyagram, bir sistemin belirli bir zamandaki anlık görüntüsüdür. Bu anlık görüntüden sonraki her kod değişikliği, diyagram ile gerçeklik arasında bir delta oluşturur. Bireysel deltalar genellikle küçüktür; yeni bir servis, yeniden adlandırılmış bir bileşen, eklenen bir bağımlılık gibi. Her birini ayrı ayrı belgelemek kolaydır. Sorun şu ki, hiç kimse bunları artımlı olarak belgelemiyor, çünkü her değişiklik için diyagramı güncellemek, anında fayda sağlamayan bir ek yük olarak algılanıyor. Kaydedilmemiş 100 deltadan sonra, diyagram esasen yanlıştır. 1,000 deltadan sonra ise büyük ölçüde kurgusaldır.

2. Eksik kaynak sorunu. Çizdiği kodla programatik bir bağlantısı olmayan bir diyagramın, ne zaman yanlış hale geldiğini tespit edecek bir mekanizması yoktur. Kod tabanındaki bir değişiklik diyagramdaki bir iddiayla çeliştiğinde tetiklenen bir sinyal yoktur. Diyagram ve kod, aynı sistemi tanımlayan ancak yalnızca diyagramı çizen kişilerin zihninde ve yalnızca bu kişiler hatırladıkları sürece var olan bağlantısız eserlerdir.

3. Sahiplik kayması sorunu. Mimari diyagramlar genellikle belirli bir kişi tarafından belirli bir anda oluşturulur. Bu kişi ayrıldığında, diyagramı doğru kılan örtük bilgi, hangi bileşenlerin kasıtlı olarak atlandığı, hangi ilişkilerin basitleştirildiği, hangi etiketlerin daha karmaşık bir şeyin kısaltması olduğu anlayışı da onunla birlikte gider. Diyagramın yeni sahibi, kendisinin oluşturmadığı, tam olarak anlamayabileceği ve tasarlamadığı bir kod tabanına karşı sürdürme konusunda hiçbir teşviki olmayan bir yapıtı devralır.

4. Aşırı hassasiyetin yol açtığı bozulma sorunu. Çok fazla ayrıntı gösteren diyagramlar, uygun soyutlamayı gösteren diyagramlara göre daha hızlı eskimeye başlar. Her mikro hizmeti, her API uç noktasını ve her veritabanı tablosunu gösteren bir diyagramın her dağıtım için güncellenmesi gerekir. Hizmet alanlarını ve bunların temel etkileşim modellerini gösteren bir diyagramın ise yalnızca alan sınırları değiştiğinde güncellenmesi gerekir. Aşırı hassas diyagramların eskime yarı ömrü sprintlerle ölçülürken, uygun şekilde soyutlanmış diyagramların eskime yarı ömrü çeyreklerle ölçülür.

5. Biçim kilitlenmesi sorunu. Visio dosyaları, PowerPoint slaytları, PNG dışa aktarımları veya PDF ekleri olarak saklanan diyagramlar programatik olarak oluşturulamaz, doğrulanamaz veya karşılaştırılamaz. "Bu diyagram hala kodla eşleşiyor mu?" diye sormanın bir yolu yoktur çünkü diyagram piksel tabanlı bir görüntüdür ve kod metindir. Diyagram oluşturma sırasında yapılan biçim seçimi, diyagramın tasvir ettiği sisteme karşı doğrulanıp doğrulanamayacağını belirler.

Eski Sistem Dokümantasyon Felaketi

Aktif geliştirme ekiplerine sahip modern bulut tabanlı sistemler için, diyagramların güncelliğini yitirmesi, mimariyi kod olarak ele alma uygulamaları, canlı dokümantasyon araçları ve mühendislik disiplini ile çözülebilecek bir yönetim problemidir. Sistem sık sık değişir; süreç doğruysa diyagram da buna uyacak şekilde güncellenebilir.

Eski sistemler için sorun, sadece derecesi bakımından değil, türü bakımından da farklıdır.

1992 yılında bir ana bilgisayar sistemi tasarım incelemesi sırasında çizilen bir mimari diyagramı, oluşturulmasından bu yana 30 yıllık kod değişikliğini biriktirmiş olabilir. Karmaşık bir COBOL portföyünde her yıl yapılan aktif bakım, yüzlerce commit, yeni program eklenmesi, eski programların kullanımdan kaldırılması, copybook'ların güncellenmesi ve JCL iş akışlarının yeniden düzenlenmesi anlamına gelir. 1992'deki diyagram o zaman doğruydu. O zamandan beri her yıl giderek daha az doğru hale geldi. 2026 yılına gelindiğinde, diyagram ile sistem arasındaki fark, orijinal sistemin kendisinden daha büyük olabilir; diyagramda yer almayan yeni programların sayısı, orijinal sistemde hala tasarlandığı gibi çalışan programların sayısından daha fazla olabilir.

Bu durumu sadece rahatsız edici olmaktan ziyade felakete dönüştüren şey, diyagramın nasıl kullanıldığıdır. Modernizasyon ekibi sistemi değerlendirmek için geldiğinde, diyagramın yanlış olduğunu bilmiyorlar. Ne kadar yanlış olduğunu bilmelerinin bir yolu yok. Diyagram profesyonel görünüyor. Bileşen kutuları, ilişki okları, açıklamalar içeriyor. Birinin bu sistemi yeterince iyi anladığını ve çizdiğini gösteriyor. Ekip bunu başlangıç ​​noktası olarak kullanıyor ve yanlış bir başlangıç ​​noktası üzerine kurulu her analiz yanlış sonuçlar doğuruyor.

Docuwriter denetim çerçevesi bunu açıkça belirtiyor: Doğru bir dokümantasyon denetimi, "belirsiz huzursuzluğu incelenebilir gerçeklere dönüştürür." Eski sistemler için dokümantasyon denetimi neredeyse her zaman aynı bulguyu ortaya koyar: Diyagramlar ya eksiktir ya da o kadar eskidir ki, yıllardır var olmayan bir sistemi temsil ederler. Nihayet ortaya çıkarılan incelenebilir gerçekler, üzerinde çalışılan sistemden önemli ölçüde farklı bir sistemi tanımlar.

Spesifik hata modu: Bir modernizasyon ekibi, 1992 diyagramından geçiş kapsamını tahmin ediyor. Bu diyagram 180 bileşen gösteriyor. Gerçek kod tabanının yapısal analizi, 340 programı ortaya çıkarıyor; bunların 80'i ölü kod, diğer 40'ı ise 1992'den sonra eklenmiş ve hiçbir zaman diyagrama dahil edilmemiş kodlar. Yeni kodun ilk satırı yazılmadan önce kapsam tahmini iki kat hatalıydı.

Bayatlık Oranına Göre Diyagram Kategorileri

Tüm diyagramlar aynı hızda eskimez. Eskime hızı, diyagramın neyi tasvir ettiğine, tasvir edilen unsurların ne sıklıkla değiştiğine ve diyagramın bu unsurları ne kadar hassas bir şekilde temsil ettiğine bağlıdır.

Diyagram TürüSıkça Değişen ŞeylerBayatlık OranıAzaltma Önceliği
Servis/parça envanteriYeni hizmetler eklendi, eski hizmetler kaldırıldı.YüksekKritik — en yüksek değişim sıklığı
Bağımlılık/entegrasyon haritasıAPI'ler eklendi, entegrasyonlar değiştirildi, veri akışları düzenlendi.YüksekKritik — her dağıtım bunu değiştirebilir.
Veri modeli / ERDŞema değişiklikleri, yeni tablolar, sütun değişiklikleriOrta-yüksekYüksek — aktif geliştirmede şema değişiklikleri sık görülür.
Sıra diyagramlarıİş mantığı değişiklikleri, API sözleşmesi güncellemeleriOrtaYüksek — herhangi bir iş akışı değişikliği bunları geçersiz kılar.
Altyapı / dağıtımKod tabanlı altyapı, sık sık değişime yol açar.YüksekOrta boy — IaC araçları bunları otomatik olarak oluşturabilir.
Etki alanı / sınırlı bağlamOrganizasyonel ve mülkiyet değişiklikleridüşük-ortaDüşük — etki alanı sınırları üç ayda bir veya daha kısa sürede değişir.
Karar kayıtları (ADR'ler)Nadiren değişir (kararlar tarihseldir)Çok düşükDüşük — bir kez doğru şekilde kaydedildikten sonra, doğruluğunu korur.
Program çağrı grafiği (COBOL)Kodda yapılan her değişiklik bunu potansiyel olarak değiştirir.Çok yüksekMiras için kritik öneme sahip — görünmez değişiklikler
Kopya defteri / şema (COBOL)Her FD değişikliği birden fazla programı etkiler.YüksekEski sistemler için kritik öneme sahip — değişiklikler sessizce zincirleme reaksiyonla gerçekleşir.

En alttaki iki satır, standart dokümantasyon kılavuzunda ele alınmayan, eski sürüme özgü girdilerdir. Bir COBOL program çağrı grafiği, çağrı ağacındaki herhangi bir programda yapılan her kod değişikliğiyle potansiyel olarak geçersiz hale gelir. 200 program tarafından paylaşılan bir copybook, copybook değiştiğinde her program için geçersiz hale gelir. Bu diyagramlar, herhangi bir kurumsal portföydeki en yüksek güncelliğini yitirme oranına ve güncelliğini yitirdiğinde en ciddi sonuçlara sahiptir, çünkü tanımladıkları programlar en kritik iş süreçlerini yürüten programlardır.

Kaynak İzleme Çözümü: Diyagramların Kaynağına Kadar İzini Sürmek

Dokümantasyon borcunun temel nedeni, dokümantasyon güncelleme sürecinin olmaması değil, kaynak takibinin, yani bir diyagram öğesinden temsil ettiği kod öğesine kadar izlenebilir bağlantının olmamasıdır. Kaynak takibi olmadan, güncelliğini yitirmişliği tespit edecek bir mekanizma yoktur. Kaynak takibi ile güncelliğini yitirmişlik tespiti otomatiktir: eğer kod öğesi diyagram oluşturulduğundan beri değişmişse, diyagram güncelliğini yitirmiştir.

Belgelerin kaynağına ilişkin bilgiler iki düzeyde mevcuttur:

Statik kaynak Statik kaynak izleme, belirli bir zaman noktasında koddan oluşturulan, oluşturma zaman damgası ve belgenin yansıttığı kod durumuna (commit hash, sürüm, analiz tarihi) referans içeren bir dokümantasyondur. Statik kaynak izleme, güncelliğini yitirmeyi önlemez, ancak güncelliğini yitirmenin tespit edilebilir olmasını sağlar: zaman damgası, dokümantasyonun hangi commit'ten oluşturulduğunu gösterir. abc123 belirli bir tarihte ve mevcut commit şudur: def456 Daha sonraki bir tarihte. İki commit arasındaki boşluk, dokümantasyon ile mevcut kod arasındaki boşluktur.

Dinamik kaynak izleme , koddan sürekli olarak üretilen ve ilgili her kod değişikliğinde yeniden oluşturulan bir dokümantasyondur. Dokümantasyon her zaman günceldir çünkü her zaman mevcut kod durumundan türetilir. Bu, yaşayan dokümantasyon modelidir; birilerinin hatırladığında güncellediği diyagramlar değil, kod her değiştiğinde koddan yeniden oluşturulan diyagramlardır.

Eski bir COBOL portföyü için pratik fark şudur: Statik bir kaynak izleme yaklaşımı, bağımlılık diyagramını mevcut COBOL kaynak analizinden oluşturur ve zaman damgası ekler. Her hafta analiz yeniden çalıştırılabilir ve yeni diyagram öncekiyle karşılaştırılabilir. Değişiklikler, ardışık analiz çıktıları arasındaki farklar olarak görünür. Dinamik bir kaynak izleme yaklaşımı, analizi ana bilgisayar değişiklik yönetimi hattına entegre eder ve bir program üretime alındığında güncellenmiş bir diyagram oluşturur.

Diyagramları Kod Olarak Kullanma: Neler İşe Yarar ve Neler Eksik Kalır

Eski ve statik diyagramlara modern yanıt, mimari dokümantasyonu sürüm kontrolü yapılabilen, karşılaştırılabilen, incelenebilen ve programatik olarak oluşturulabilen bir metin biçiminde ifade eden kod tabanlı diyagramlardır. Mermaid, PlantUML ve kod biçimindeki C4 modeli başlıca araçlardır.

For modern cloud-native systems, diagrams-as-code solves several of the staleness mechanisms: #mermaid-rlk-r1 { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 .edge-animation-slow { stroke-dashoffset: 900; animation: 50s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .edge-animation-fast { stroke-dashoffset: 900; animation: 20s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .error-icon { fill: rgb(204, 120, 92); } #mermaid-rlk-r1 .error-text { fill: rgb(51, 135, 163); stroke: rgb(51, 135, 163); } #mermaid-rlk-r1 .edge-thickness-normal { stroke-width: 1px; } #mermaid-rlk-r1 .edge-thickness-thick { stroke-width: 3.5px; } #mermaid-rlk-r1 .edge-pattern-solid { stroke-dasharray: 0; } #mermaid-rlk-r1 .edge-thickness-invisible { stroke-width: 0; fill: none; } #mermaid-rlk-r1 .edge-pattern-dashed { stroke-dasharray: 3; } #mermaid-rlk-r1 .edge-pattern-dotted { stroke-dasharray: 2; } #mermaid-rlk-r1 .marker { fill: rgb(145, 145, 141); stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 .marker.cross { stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 svg { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; } #mermaid-rlk-r1 p { margin: 0px; } #mermaid-rlk-r1 .label { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; color: rgb(25, 25, 25); } #mermaid-rlk-r1 .cluster-label text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span p { background-color: transparent; } #mermaid-rlk-r1 .label text, #mermaid-rlk-r1 span { fill: rgb(25, 25, 25); color: rgb(25, 25, 25); } #mermaid-rlk-r1 .node rect, #mermaid-rlk-r1 .node circle, #mermaid-rlk-r1 .node ellipse, #mermaid-rlk-r1 .node polygon, #mermaid-rlk-r1 .node path { fill: rgb(240, 240, 235); stroke: rgb(217, 216, 213); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label text, #mermaid-rlk-r1 .node .label text, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-anchor: middle; } #mermaid-rlk-r1 .node .katex path { fill: rgb(0, 0, 0); stroke: rgb(0, 0, 0); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label, #mermaid-rlk-r1 .node .label, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-align: center; } #mermaid-rlk-r1 .node.clickable { cursor: pointer; } #mermaid-rlk-r1 .root .anchor path { stroke-width: 0; stroke: rgb(145, 145, 141); fill: rgb(145, 145, 141) !important; } #mermaid-rlk-r1 .arrowheadPath { fill: rgb(11, 11, 11); } #mermaid-rlk-r1 .edgePaths .path { stroke: rgb(145, 145, 141); stroke-width: 1px; } #mermaid-rlk-r1 .flowchart-link { stroke: rgb(145, 145, 141); fill: none; } #mermaid-rlk-r1 .edgeLabel { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .edgeLabel p { background-color: rgb(245, 230, 216); } #mermaid-rlk-r1 .edgeLabel rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .labelBkg { background-color: rgba(245, 230, 216, 0.5); } #mermaid-rlk-r1 .cluster rect { fill: rgb(204, 120, 92); stroke: rgb(138, 115, 107); stroke-width: 1px; } #mermaid-rlk-r1 .cluster text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .node .collapsed-indicator { fill: rgb(138, 115, 107); stroke: none; opacity: 0.6; } #mermaid-rlk-r1 .node .collapsed-separator { stroke: rgb(138, 115, 107); stroke-width: 0.75px; } #mermaid-rlk-r1 div.mermaidTooltip { position: absolute; text-align: center; max-width: 200px; padding: 2px; font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 12px; background: rgb(204, 120, 92); border: 1px solid rgb(138, 115, 107); border-radius: 2px; pointer-events: none; z-index: 100; } #mermaid-rlk-r1 .flowchartTitleText { text-anchor: middle; font-size: 18px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 rect.text { fill: none; stroke-width: 0; } #mermaid-rlk-r1 .icon-shape, #mermaid-rlk-r1 .image-shape { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .icon-shape p, #mermaid-rlk-r1 .image-shape p { background-color: rgb(245, 230, 216); padding: 2px; } #mermaid-rlk-r1 .icon-shape .label rect, #mermaid-rlk-r1 .image-shape .label rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .label-icon { display: inline-block; height: 1em; overflow: visible; vertical-align: -0.125em; } #mermaid-rlk-r1 .node .label-icon path { fill: currentcolor; stroke: revert; stroke-width: revert; } #mermaid-rlk-r1 .node .neo-node { stroke: rgb(217, 216, 213); } #mermaid-rlk-r1 [data-look=”neo”].node rect, #mermaid-rlk-r1 [data-look=”neo”].cluster rect, #mermaid-rlk-r1 [data-look=”neo”].node polygon { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].swimlane.cluster rect { filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node path { stroke: url(“#mermaid-rlk-r1-gradient”); stroke-width: 1px; } #mermaid-rlk-r1 [data-look=”neo”].node .outer-path { filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node .neo-line path { stroke: rgb(217, 216, 213); filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node circle { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node circle .state-start { fill: rgb(0, 0, 0); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon { fill: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon-neo path { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 :root { –mermaid-font-family: system-ui,”Segoe UI”,Roboto,Helvetica,Arial,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,”Kohinoor Devanagari”,”Kohinoor Bangla”,”Kohinoor Telugu”,”Tamil Sangam MN”,”Kohinoor Gujarati”,”Malayalam Sangam MN”,”Nirmala UI”,”Noto Sans Devanagari UI”,”Noto Sans Devanagari”,”Noto Sans Bengali UI”,”Noto Sans Bengali”,”Noto Sans Telugu UI”,”Noto Sans Telugu”,”Noto Sans Tamil UI”,”Noto Sans Tamil”,”Noto Sans Gujarati UI”,”Noto Sans Gujarati”,”Noto Sans Kannada UI”,”Noto Sans Kannada”,”Noto Sans Malayalam UI”,”Noto Sans Malayalam”,Thonburi,”Leelawadee UI”,”Noto Sans Thai UI”,”Noto Sans Thai”,Kefa,Ebrima,”Noto Sans Ethiopic”,”Abyssinica SIL”,sans-serif,ui-sans-serif,system-ui,-apple-system,”Segoe UI”,Roboto,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,sans-serif; }API GatewayAuth ServiceOrder ServiceOrder DBNotification ServiceUser DB

Bu Mermaid diyagramı, temsil ettiği kodla birlikte depoda yer almaktadır. Bir geliştirici yeni bir hizmet eklediğinde, bu dosyayı aynı çekme isteğinde günceller. Kod incelemesi, diyagram değişikliğini de içerir. Dokümantasyon ve kod birlikte hareket eder.

Diyagramların kod olarak kullanılmasının çözemediği sorunlar:

Eski sistem dokümantasyonu sorununu çözmüyor. Bir geliştiricinin Git çekme isteği yerine derleme JCL'si göndererek ana bilgisayar kütüphanesine eklediği bir COBOL programı, Mermaid dosya güncellemesini tetiklemiyor. Ana bilgisayar değişiklik yönetimi süreci ve Git tabanlı dokümantasyon süreci, otomatik senkronizasyonu olmayan ayrı sistemlerdir.

Bu, aşırı hassasiyet sorununu çözmüyor. Her yeni hizmet için manuel olarak güncellenmesi gereken bir Mermaid diyagramı, sürecin yerini alması gereken insan disiplinini hala gerektiriyor. Diyagramın güncellenmesi manuel bir adım ise, atlanacaktır.

Eski diyagramları geriye dönük olarak düzeltmez. Mevcut makine tarafından okunabilir dokümantasyonu olmayan bir COBOL portföyü için, kod olarak diyagramlar gelecekteki dokümantasyon için bir çerçeve sağlar ancak mevcut dokümantasyonu oluşturmaz.

Eski Sistemler için Yapısal Analiz Yaklaşımı

Geliştirme iş akışının Git'ten geçmemesi, mevcut dokümantasyonun metin tabanlı bir yaklaşım için başlangıç ​​noktası olamayacak kadar eski olması veya kod tabanının hiçbir zaman resmi olarak belgelenmemiş olması gibi nedenlerle diyagramların kod olarak gösterilmesinin pratik olmadığı eski sistemler için, yapısal kod analizi, sıfırdan başlayarak güncel ve doğru dokümantasyon üreten tek mekanizmadır.

Yapısal analiz, gerçek kodu, COBOL programlarını, JCL iş akışlarını, copybook'ları, gömülü SQL'i ayrıştırır ve bağımlılık ilişkilerini, program envanterlerini ve veri yapılarını doğrudan kodun içerdiği bilgilerden türetir. Çıktı, kodu anlayan bir insan tarafından çizilmiş bir diyagram değil; kodun kendisinden algoritmik olarak türetilmiş bir diyagramdır. Doğruluğu, onu çizen geliştiricinin hafızasıyla değil, analizin doğruluğuyla sınırlıdır.

İş akışı:

darbe

# Structural analysis pipeline for COBOL documentation
# Step 1: Parse all COBOL source in the portfolio
smart-ts-xl analyze --source /cobol/src --output /docs/analysis/

# Step 2: Generate dependency graph (always current)
smart-ts-xl diagram --type dependency-graph \
    --format mermaid \
    --output /docs/dependency-graph.md

# Step 3: Generate program inventory (always current)
smart-ts-xl report --type program-inventory \
    --format markdown \
    --output /docs/program-inventory.md

# Step 4: Diff against previous analysis (detect what changed)
smart-ts-xl diff \
    --baseline /docs/analysis/2026-09-01/ \
    --current  /docs/analysis/2026-10-01/ \
    --output   /docs/changes/delta-report.md

İki ardışık analiz arasındaki farkı gösteren delta raporu, diyagramın statik kaynağının otomatik olarak ürettiği değişiklik günlüğüdür. Eklenen programlar, kaldırılan programlar, değişen bağımlılıklar, değiştirilen copybook'lar: bunların hepsi insan eliyle belgelemeye gerek kalmadan delta raporunda görünür.

Son analiz sonucunda elde edilen diyagram, analiz tarihi itibariyle güncel olan dokümantasyondur. Analizin haftalık veya her üretim promosyonunda tetiklenen bir program dahilinde çalıştırılması, sürekli manuel dokümantasyon çabası gerektirmeden, tanımlanmış bir tempoda güncel dokümantasyon üretir.

Belgeleme Önleme Çerçevesi

Belgeleme borcunu önlemek, beş eskime mekanizmasına yönelik somut ve uygulanabilir uygulamalar gerektirir:

Biriken delta problemine karşı:

  • Bir analiz sıklığı belirleyin: yüksek hızlı sistemler için haftalık, istikrarlı sistemler için aylık.
  • Her analiz çalıştırmasında koddan dokümantasyon oluşturun, bunu manuel olarak yapmayın.
  • Her çalıştırma için, son analizden bu yana nelerin değiştiğini gösteren bir delta raporu oluşturun.

Kaynak bilgisinin eksikliği sorununa karşı:

  • Her diyagram, oluşturulma kaynağını (kod analizi tarihi ve sürümü) içerir.
  • Bir diyagramı, nasıl ve ne zaman oluşturulduğunu kaydetmeden asla yayınlamayın.
  • Oluşturulan diyagramları, onları üreten analiz çıktılarıyla birlikte saklayın.

Mülkiyet kayması sorununa karşı:

  • Dokümantasyon oluşturma, bireysel bir sorumluluk değil, bir süreç adımıdır.
  • Belgelerin mülkiyeti boru hattına aittir; hiçbir bireyin ayrılması bu boru hattını bozamaz.
  • Oluşturulan belgelerin, sahiplerinden ayrılıp gidecek bir sahibi yoktur.

Aşırı hassasiyet problemine karşı:

  • Her diyagram türünü oluşturmadan önce uygun soyutlama düzeyini tanımlayın.
  • Bileşen envanter diyagramları, fonksiyon seviyesinde değil, hizmet/program seviyesinde olmalıdır.
  • İlişki diyagramları, bireysel çağrı düzeyinde değil, etki alanı sınır düzeyinde gösterilir.
  • Ayrıntılı diyagramlar (çağrı grafikleri, veri şemaları) elle çizilmek yerine oluşturulur.

Biçim kilitlenmesi sorununa karşı:

  • Oluşturulan diyagramlar metin tabanlı formatlarda (Mermaid, GraphViz DOT, SVG) kullanılabilir.
  • Visio, PowerPoint veya PDF formatında tek başına mimari dokümantasyon yok.
  • Diyagram kaynakları, belgeledikleri kodla birlikte sürüm kontrolünde saklanır.

Ne kadar SMART TS XL Eski Belgeleme Borçlarını Ele Alıyor

Eski COBOL ve ana bilgisayar portföyleri için, SMART TS XL Yapısal analiz motoru, kanıta dayalı dokümantasyonu mümkün kılan ve "koddan yeniden oluşturma"yı "2009 SharePoint diyagramını güncelleme"ye pratik bir alternatif haline getiren araçtır.

Statik kod analizi özelliği, her COBOL programını, copybook'u, JCL iş akışını ve gömülü SQL ifadesini ayrıştırarak, doğru eski sistem dokümantasyonunun temel katmanını oluşturan program envanterini, karmaşıklık ölçütlerini ve ölü kod tanımlamasını üretir. Bu envanter, her zaman eksik, her zaman güncel olmayan ve kimsenin bilmediği şekillerde her zaman yanlış olan, elle tutulan program listesinin kanıta dayalı bir alternatifidir.

Uygulama bağımlılık haritalaması, mimari dokümantasyonun temel unsuru olan bağımlılık grafiğini, her CALL ilişkisini, her COPY ilişkisini ve programlar arasındaki her veri akışını oluşturur. Bu grafik, her analiz çalıştırmasında koddan yeniden oluşturulur ve çalıştırmalar arasında insan dokümantasyon çabası gerektirmeden, son analiz itibariyle güncel bir bağımlılık diyagramı üretir.

Etki analizi özelliği, delta dokümantasyonunu oluşturur: kod tabanında bir değişiklik yapıldığında, etki analizi önceki duruma göre değişen her şeyi belirler. Bu, biriken delta sorununu ele alan otomatik delta raporudur; diyagram-gerçeklik arasındaki farkı genişletecek her değişiklik otomatik olarak yakalanır ve belgelenir.

Kurumsal arama özelliği, dokümantasyonu sorgulanabilir hale getirir: belirli bir alt programı çağıran her programı (bir bileşen için çağrı grafiği parçası), belirli bir copybook'u içeren her programı (paylaşılan bir bileşenin bağımlılık kapsamı), belirli bir tarihten sonra değiştirilen her programı (belirli bir zaman dilimi için değişiklik günlüğü) bulun. Bu arama özelliği, dokümantasyon arayüzüdür; mevcut sistem durumu hakkında soruları, yıllar öncesine ait olabilecek statik bir diyagramdan değil, mevcut analizden yola çıkarak yanıtlayan araçtır.

Faaliyet gösteren kuruluşlar için miras modernizasyonu programları SMART TS XLDokümantasyon oluşturma, modernizasyon programının kapsamını tanımlamak, geçiş dalgalarını sıralamak ve sonuçları doğrulamak için ihtiyaç duyduğu bağımlılık diyagramı, program envanteri ve veri şeması dokümantasyonunun oluşturulması için ön koşuldur. Bu dokümantasyon SharePoint arşivinden gelemez. Koddan gelmelidir.

Tek doğru diyagram, koddan türetilen diyagramdır.

SharePoint sayfasındaki 2009 mimari diyagramı, birisi açıkça silene kadar varlığını sürdürecektir. Sistem nasıl çalışıyor diye soran yeni geliştiricilere gönderilmeye devam edecektir. Artık doğru bir şekilde tanımlamadığı bir sistem hakkındaki kararları etkilemeye devam edecektir. Diyagram ile sistem arasındaki uçurum, her taahhüt, her dağıtım, her program ekleme ve kaldırma işlemiyle birlikte genişlemeye devam edecektir.

Alternatif, "diyagramları daha sık güncellemek" değildir. Sürekli değişen koda karşı insan disiplini gerektiren süreçlerin bilinen bir başarısızlık modu vardır: disiplin başarısız olur. Alternatif ise koddan türetilen, kodu doğruluk kaynağı olarak kullanan, kod değiştiğinde otomatik olarak yeniden oluşturulan ve her okuyucuya tam olarak ne kadar güncel olduğunu söyleyen analiz zaman damgasını taşıyan dokümantasyondur.

Modern bulut sistemleri için, kod olarak diyagramlar ve canlı dokümantasyon araçları bunu sağlar. Eski COBOL sistemleri için ise yapısal kod analizi bunu sağlar. Mekanizma farklıdır; prensip aynıdır: diyagram, koddan türetildiğinde doğrudur ve onu üreten koddan ayrıldığı andan itibaren birikmeye başlar.

Güncel kalan tek diyagram, kod tarafından çizilen diyagramdır.