Scrum Ekipleri için ideal dökümantasyon önerileri
Development alanında çalışıyorsanız veya development projeleri içersinde yer alan bir cycle’ın içerisindeyseniz…Aslında bir çoğumuzun karşılaştığı veya gözden kaçırdığı bir konuya değinmeye çalışacağız…Son günlerde hepimizin genellikle önemsemediği veya işin en sonuna bırakıldığı bir konu aslında dökumantasyon…
Dökumantasyon’un önemini en iyi; projede uzun süre çalışan bireylerin, işten ayrılmaya karar verdiğinde veya projeye yeni giren birinin adaptasyon sürecinde ortaya çıkıyor…
Aslına bakarsanız dökumantasyon, projedeki knowledge’ı en iyi ortaya koyabileceğimiz bir alan diye düşünüyorum.(her ne kadar da proje içerisindeki bireylerin günün sonunda kaçtığı bir konu olsa da…)
Genellikle ilk başlarda iyi tanımlamalar ve yalın bir ifadeyle hazırlanmış olsa da, ilerledikçe başlangıçtaki durumun tersine dönen ve herhangi bir özen gösterilmeyen, oldukça karışık hale gelen bir durumdur.
Farklı bir konu ise; dökumantasyon’u hazırlayan bireylerin aslında ekip içerisinde kendi domain’inde farklılaşmış bir jargon ile hazırlanmasıdır…Bu durum proje yeni giren; tester’ından business analyst’ine, scrum master’ından product owner’ına kadar, insanların hali hazırda bulunan jargon’u ve business domain’i anlamalarını zorlaştırmaktadır.
Bir önceki konuyla bağımlı olarak ise; projeye yeni giren bir junior’ın anlayabileceği bir seviyede olmaması; adaptasyon sürecini uzatan ve karmaşık hale getiren bir konudur…Adaptasyon sürecinin uzaması, aslında günün sonunda iş gücü maliyetini artıran bir konu haline gelecektir.(…bireylerin junior veya senior olmasından bağımsız olarak.)
Farklı bir perspektifden konuya bakmak istersek; ilk olarak elimizde bulunan veya ortaya koyacağımız knowledge’ı iki ana başlık altında değerlendirebilmemiz mümkün…Bunlar; Business Domain & Technical Domain olarak ikiye ayrılabilir.(başlıklar kendi içerisinde de ayrılabilir, projenin çıktılarına ve ekibin yapısına göre de değişebilir…)
Her iki domainde de yer alacak ortak konular veya kendi içinde farklılaşan konular olabilir.Ortak konulara değinebilmek gerekirse;
- Belirlenmiş bir yazı font’u ve boyutu kullanılmalı.(Belirlenmiş font ve boyutun önemi şu şekilde açıklanabilir; etkileşimi arttırmak ve ekip içerisinde belli bir format yakalayabilmek)
- Oluşturulacak sayfaların, kategorilendirilmesi ve naming-convention’a dikkat edilmesi(Oluşturulacak olan sayfaların isim dönüşümü ve kategorilendirilmesi; projedeki yapının ve dökumantasyon’ un büyüdükçe aradığımız dökumana kolayca erişebilmek, dışarıdan bakıldığında hangi sayfanın içeriğinin ne olduğunu az-çok tahmin edebilmek…)
- Dökumanlar’ın tamamı yalın ve gereksiz bilgilerden arındırılmış, günün sonunda bir ‘junior’ tarafından okunabiliyor ve anlaşılabilir olması gerekir
İlk domainimizde yer alan konuya değinebilmek gerekirse; Business Domain, bir projedeki günün sonunda ortaya konan ürün ile ilgili, belli başlı sınırların belirlendiği ve ürünün her bir fonksiyonun açıklanabilir olduğu durumların ele alındığı kısım olmalıdır…Detaylıca inceleyebilmek gerekirse;
- Wiki veya Confluence gibi online olarak her yerden erişilebilir bir yerde host edilmesi
- Ekipteki üyelerin, iletişim bilgilerinin ve görev tanımlarının yer aldığı bir team overview kısmının oluşturulması
- Projenin Scope’u (Scope of the Project; Projenin uçtan uca tüm fonksiyonelliği/işlevliği ve ürününün gereksinimlerini kapsayacak şekilde ortaya konması..), Domain Vision’(ürünün temel olarak ortaya konan işlevi) gibi ürüne/proje ait spesifik değerlerin ortaya konması.
- Konu/konu başlıklarının sonsuza giden bir ‘waterfall’a dönüşmemesi!(bu durum büyük projelerde meydana gelen bir konu; bir wiki/confluence sayfasında iç içe geçirilmiş sayfaların tıkladığınızda uzun uzadıya açılarak gitmesi…Aslında bu durum; konu başlıklarının iyi seçilmesi ve outdate bilgilerin silinip, güncel/aktuel bilgilerin konulmasıyla ve bilgilerin daima güncel tutulması ile bu durumun önüne geçilebilir…)
- Bağımsız bir Jargon kullanılması(…aslında yazının başında dikkate aldığımız gibi, proje’nin yarın bizlere neler getireceğini ve mevcut yapının veya takım organizasyonun nasıl değişeceğini hiç birimiz kestiremeyiz…İyi kurgulanmış bir scrum ekibinde, scrum master’ından product owner’ına, business analyst’inden tester’ına…junior’undan senior’una hatta Architect seviyesine kadar insanlar girebilir/çıkabilir…Confluence/Wiki gibi teknik konulardan arınmış bir dökumantasyon sürecinde, herhangi bir jargon’a bağlı kalmadan; yalın ve anlaşılabilir ifadelerin kullanılması, takım uyumunu da arttıracaktır!)
- Mümkün olduğunca, projenin yapısını ve genel resmini, resmedin/diagramlar ile gösterin(projedeki domaini ve birbiri içerisinde yer alan etkileşimleri diagramlar ile resmetmek, daha anlaşılır ve akılda kalıcı özet bir ifadeye dönüşecektir.)
- Business kısmında; teknik konuların ele alınmaması veya yüzeysel olarak yaklaşılması gerekir.(.. bu durum tek düze monalit bir dökumantasyonu meydana getirecektir ve karmaşıklığı arttıracaktır.)…Herhangi bir code-block’nun veya uml/user-sequence/collaboration diagram gibi teknik konuların burada yer almıyor olması gerekir.
- Proje içerisindeki veya ürün ile bağlantılı credentiallar’ın veya şifrelerin dökuman üzerinde tutulmaması gerekir.(ciddi bir güvenlik açığıdır, keePass gibi yöntemler tercih edilebilir)
İkinci domain’e değinebilmek gerekirse; birebir ürünle ‘sıfır noktası’nda yer aldığımız kısım…Bu domain’de projedeki ana yapının açıklanması ve servislerin nerelere gittiği, sonucunda bize ne döndüğü, yapısal olarak diagramlarla ifade edilen; projenin ürün bazlı teknik kısmı, aslında işin mutfak kısmı yer almakta;
- Mümkünse teknik dökuman ingilizce olmalıdır.(Gün içerisinde, nasıl bir developer’ın yazdığı class’a ve içerisinde yer alan herhangi bir argüman veya bir fonksiyonun isimlendirilmesi İngilizce ise<ki öyle olmalıdır>…bir DevOps Engineer’ın veya bir Cloud Archtect’in de Jenkins job’larındaki naming-convention’ı da ingilizce oluyorsa…Teknik domainimizde yer alan dökumanımız İngilizce olmalıdır)
- Uzun uzadıya giden cümlelerden kaçının.(Teknik domainimizde yer alan, ifadelerin mümkün mertebe kısa olması ve bir/iki cümlede açıklanabilir bir ifadeyle yer alması gerekmektedir.Burada önemli olan; bir feature’ın ne işe yaradığı ve hangi argümanları içerdiğidir)
- Github/Bitbucket/GitLab gibi ürün yapısının içerisinde ayrı bir folder’da host edilmelidir
- Projenizin ana yapısında, ‘/docs’ veya ‘/documentation’ adı altında ayrı bir yerde tutmalısınız
- Projeniz büyükdükçe, dökumantasyonunuzda beraberinde büyüyecektir; dolayısıyla konu başlıklarına, işlevselliğine ve kendi içerisinde yer alan konulara göre ayrışacaktır ve kategorisel bir hale dönüşecektir…
- Daima güncel olmalıdır ve sprint hedeflerine dahil edilmelidir.(dökumantasyonun sprint hedefleri arasında yer alması, hem güncel olmasını sağlayacak hem de developer üzerinden sonradan oluşan iş-gücünü azaltacaktır)
- Naming-convention’a dikkat edilmeli, mümkünse belirli bir format belirlenmelidir(yazdığımız class’lar veya Jenkins üzerinde oluşturuduğumuz ve derlediğimiz job’ları belirli bir convention çerçevesinde yapıyoruz…Dökumantasyonu’da aynı şekilde belirli bir formatta isimlendirebilir ve anlaşılır hale getirebiliriz…Bir format örnek verilmek istenirse; UPPER_CASE_SNAKE_CASE veya kebab-case convention tipleri kullanılabilir.)
- Dökumanınızda mutlaka bir flow belirleyin…Örnek; 1)Overall 2)Pre-requirements 3)API References gibi
Dökumantasyon daha detaylı bir şekilde de ele alınabilir.Bu yazıda aslında hepimizin bildiği fakat, gözden kaçırdığı veya atladığı konuları genel olarak ele almaya çalıştım
Keyifli olabilmesi dileğiyle
Arda Batuhan Demir
Kaynakça
