Mimariyi Kodla Birlikte Yönetmek
Markdown (MD) basit bir işaretleme ile profesyonel görünüşlü dokümanlar oluşturmayı sağlayan bir standarttır. HTML’e göre daha basit olup yazmak için özel bir editör olmadan yönetilebilmektedir. Kod yönetim aracı olan GIT markdown formatını desteklemektedir. GIT ortamında genelde projenin basit tanıtımı ve nasıl build alınacağını anlatmak için markdown kullanılmaktadır (readme.md). Bu yazıda markdown formatının mimari dokümantasyon için nasıl kullanılacağını şablonlar ile birlikte anlatılmaktadır.
Markdown ile Mimari Dokümantasyon
Geliştirilen yazılımın mimari tasarımı ve mimari tasarım kararlarını da kod ile birlikte yönetmek proje açısından büyük kolaylıklar sağlayacaktır. Tasarımımız kod ile birlikte konfigürasyon yönetimi ortamında tutulduğunda tasarım değişikliğini ve kod değişikliğini birlikte gerçekleştirip birlikte takip edebiliriz. Projeye yeni gelen bir mühendis kodu yeni bilgisayarına indirdiğinde sistemin mimarisini de indirip inceleme fırsatı bulur. Ayrıca World dokümanları veya confluence sayfalarını karıştırıp tasarımın en son versiyonunu bulmaya uğraşmaz.
IDE ile Markdown Doküman Hazırlama
Markdown doküman hazırlamak için kod geliştirdiğiniz Visual Studio Code ve benzeri editörlerden başka bir araca ihtiyaç duymayacaksınız (Piyasada markdonn editörler mevcut ama IDE içinden yapmak amacımız için daha pratik olacaktır.). Visual Studio Code içinde “Markdown Preview Enhanced” eklentisini kullanabilirsiniz. Bu eklenti ile VS code da markdown dokümanı görsel olarak görebiliyorsunuz (Preview). Ayrıca aynı aracı kullanarak HTML , World yada PDF doküman üretebiliyorsunuz.
UML ve C4 Diagramları
Markdown dokümanı içersine Plant UML script dili ile çizdiğiniz UML ve C4 diyagramlarını koyabilirsiniz. Böylelikle çizim dahil bütün tasarımı tek bir yerde tutmuş olursunuz. Markdown dokümanı içerisine koyduğunuz UML ve C4 diyagramları ön görüntüleme penceresinde şekil olarak görülebilecektir. (“PlantUML” isimli bir eklenti ile). Ayrıca pdf ya da html export ettiğinizde de bu diyagramları şekil olarak görebileceksiniz. GIT aracının bu PlantUML ile yazılmış tasarım scriptlerini görsel olarak gösterme özelliği bulunmaktadır. Bu şekilde Bitbucket ile kodu incelerken tasarımı da görmek mümkündür (Uygun versiyon ve konfigürasyon ile). Açık kaynak olan Github sitesinde bu özelliği henüz kullanılamamaktadır.
Eğer git sunucusu görsellemeyi desteklemiyorsa önce Visual Studio Code Plant UML eklentisi ile ya da plantuml sunucu sitesinden çizimi png yada svg yapıp ilgili çizimi Git sunucusuna atabilirsiniz. Sonrasında bu çizimi markdown dokümanda çizim linki olarak verebilirsiniz. Bu yöntemi başka araçlar ile yaptığınız çizimler içinde kullanabilirsiniz.
Arc 42 Şablonu
Arc 42, mimari dokümantasyon için oluşturulmuş bir şablondur. Bu şablona göre aşağıdaki başlıklar altında mimari tasarımı ve tasarım kararlarını yazabilirsiniz. Bu Arc42 şablonunu uygun şekilde doldurduğunuzda yazılımınız mimarisi için önemli kararları ve tasarımın temel taşlarını anlatmış olacaksınız.
1 — Giriş ve Hedefler
2 — Kısıtlamalar
3 — Bağlam ve kapsam
4 — Çözüm stratejisi
5 — Yapı taşı görünümü
6 — Çalışma zamanı görünümü
7 — Dağıtım görünümü
8 — Kavramlar
9 — Mimari kararlar
10 — Kalite Öznitelikleri
11 — Riskler ve teknik borç
12- Sözlük
Arch42 web sitesinde markdown için hazırlanmış şablona erişebilirsiniz. İlgili sitede tek bir dosya olarak ya da her bir bölüm ayrı dosya olarak taslak bulunmaktadır.
Bu şablon içerinde gerek C4 Model gerekse UML diyagramlarını kullanabilirsiniz. Örneğin 3 Bağlam ve Kapsam altında C4 kapsam diyagramı, Bölüm 5 te konteyner diyagramını ve komponent diyagramı kullanabiliriz. Bölüm 6 da C4 destek diyagramı olan Dinamik diyagram yada UML sıralı işlem (sequence) diyagram kullanılabilir. Bölüm 7 de dağılım diyagramı için C4 yada UML gösteriminden faydalanılabilir.
Bölüm 10 için Mimari Ödünleşim Analiz Yöntemi (ATAM) ile hazırlanmış tabloları kullanabiliriz. Bu kapsamda benim hazırladığım markdown tablo taslağına erişebilir ve kullanabilirsiniz.
Ben mimari kararları bu ATAM tablosunda dokümante etmeyi seviyorum. Bunun yanında Architecture Desision Records (ADR) şablonu ile de mimari kararlarınızı dokümante edebilirsiniz. Makrdown ADR (MADR) şablonunu bu amaçla kullanabilir ve kod ile birlikte tutabilirsiniz.
Sonuç
Arch 42 şablonu içerisinde C4 modeli ve UML ile geliştirilmiş diyagramların olduğu markdown formatında hazırlanmış yazılım mimari dokümanının kod ile birlikte Git yapısında tutulması önerilmektedir. Bu çözüm yüksek kalitede, yönetilebilir, versiyon kontrolü ile değişimleri izlenebilir bir mimari dokümantasyon sunmaktadır.
Alternatifler:
Bu yazıda, Git reposu içinde mimarinin dokümantasyonu için kendi kullandığım seçimlerimden bahsettim. Aynı amaç için kullanabileceğiniz başka açık kaynak ve ya ticari alternatifler de bulunmaktadır. Aşağıda benim gördüğüm bazı alternatifleri görebilirsiniz:
Belge şablonu:
- Markdown (.md): https://www.markdownguide.org/
- Restructured Text (.rst): https://docutils.sourceforge.io/rst.html
- Ascidoc: https://asciidoc-py.github.io/index.html
Script Tabanlı Tasarım Araçları
- PlantUML (UML, C4, Mindmap etc.) : https://plantuml.com/
- Mermaid (UML): https://mermaid-js.github.io/mermaid/#/
- Structurizr (C4) : https://structurizr.com/
Editorler:
- VS Code
- Intelij
Şablonlar:
- arc 42 https://arc42.org/
- Markdown ADR : https://adr.github.io/madr/
- ISO/IEC/IEEE 42010 Architecture description (AD) template:http://www.iso-architecture.org/42010/templates/, https://github.com/jam01/SDD-Template
- Şablonsuz- Çizim ve çizim dosyaları yeterli
