(Bu röportaj İngilizce olarak da mevcuttur.)
Duyuru
Yazılım dokümantasyonu sinir bozucu olabilir, ancak böyle olması gerekmez. iX dört uzmana deneyimlerini ve iyileştirme önerilerini sordu. Charlotte Scharbert, Alexander Schwartz, Falk Sippach ve Dr. Gernot Starke, yapay zeka araçlarının şu anda ne kadar kullanışlı olduğu, geliştiricilerin kullanabileceği en iyi uygulamalar, hangi tuzaklardan kaçınmaları gerektiği ve dokümantasyonun günlük işlere nasıl sorunsuz bir şekilde entegre edilebileceği hakkında bilgiler veriyor.
Başlangıçta yazılım geliştirme alanında çalışan Charlotte, daha sonra dokümantasyon alanına geçti ve şu anda teknik dokümantör olarak çalışıyor. Amaçları yazılım dokümantasyonu konusunu daha popüler hale getirmek ve dokümantasyonun zaman alıcı ve sinir bozucu olmak zorunda olmadığını göstermektir.
Alexander Schwartz, Red Hat'te Keycloak projesinde baş yazılım mühendisi ve bakım sorumlusu olarak çalışıyor ve aynı zamanda yazılım mimarı ve BT danışmanı olarak deneyime sahip. Ayrıca özel olarak IntelliJ için AsciiDoc eklentisi de dahil olmak üzere açık kaynaklı yazılımlar geliştiriyor. Konferanslarda ve kullanıcı gruplarında Java, Kubernetes, performans, iyi dokümantasyon, kimlik ve erişim yönetimi hakkında konuşuyor.
Falk Sippach, embarc Software Consulting GmbH'de yazılım mimarı, danışman ve eğitmendir. Java topluluğuna dahil olup bilgilerini makalelerde, blog yazılarında ve konuşmalarda paylaşmaktadır.
INNOQ Üyesi Dr. Gernot Starke, yazılım geliştirme ve mimari alanında koç ve danışman olarak çalışmaktadır. Arc42 ve Goal42 açık kaynak projelerinin kurucu ortağı ve sürdürücüsüdür, kitapların yazarıdır ve konferanslarda ara sıra konuşmacıdır.
Yaygın engeller: takdir eksikliği, net olmayan hedef gruplar ve talimatlar
iX: Yazılımın ve mimarisinin belgelenmesi pek popüler olmadığı yönünde bir üne sahiptir. Sizce en büyük engeller neler?
Charlotte Schabert: Bence büyük bir sorun, ev planları için mimaride veya elektrik mühendisliğinde kablo şemaları için olduğu gibi bunun için bir standart olmamasıdır. Elbette UML gibi standartlarımız var, ancak bunlar nadiren kullanılıyor ve deneyimlerime göre yazılım mimarisini temsil etmeye yalnızca kısmen uygun. Bu nedenle, genellikle birkaç ay sonra kimsenin gerçekten anlamadığı “kutu ve çizgiler”den oluşan kafa karıştırıcı bir düzenlemeyle karşılaşırsınız veya proje belgelerinde Google aramasından alınan bir resimle birlikte “altıgen bir mimari kullanıyoruz” yazıyor – hepsi bu. Dokümantasyon genellikle yalnızca projenin sonunda oluşturulur. O zaman her şeyi hatırlamak veya bir şeyin nasıl yapılandırıldığını anlamak zordur. Bu, dokümantasyonu sıkıcı ve sinir bozucu hale getirir.
Ayrıca, hızlı ve kolay bir şekilde, değişiklik yapılması durumunda daha sonra kolayca düzenlenebilecek diyagramlar oluşturabileceğiniz bazı araçlar da vardır. Deneyimlerime göre, grafiksel araçlar hızla hayal kırıklığına neden oluyor çünkü geliştiriciler kutuları sonsuza kadar taşımak istemiyor. “Kod olarak diyagramlar” iyi bir yaklaşım, ancak bence henüz tam potansiyeline ulaşmadı.
Alexander Schwartz: Dokümantasyona yönelik algılanan takdir eksikliği yaygın bir engeldir. Belgelerin aktif olarak okunduğunu ve kullanıldığını görmezlerse geliştiriciler arasında her zaman popüler değildir. Başlayabileceğiniz yer burasıdır: Bir web izleme aracı, belgelerin hangi bölümlerine ve ne sıklıkta erişildiğini gösterebilir; önlenebilir müşteri taleplerine ilişkin istatistikler ise belgelerin nerede eksik olduğunu gösterebilir. Bir yazılım mimarı veya işletme departmanı, belgeleri okuyarak ve söz konusu sistemi anlamak için sorular sorarak, belgelere olan takdirlerini gösterebilir. Örneğin, bir planlama toplantısına en son ne zaman bir belgeden bir alıntı veya grafik getirdiğinizi ve diyagramı kağıtlı sunum tahtası üzerinde yeniden çizmek yerine bunun üzerinde aktif olarak çalıştığınızı kendinize sorabilirsiniz. Belgeleme geleceğe bir yatırım olabilir, ancak bazen tam tersi olarak algılanır: Çok fazla belgelemeniz durumunda işinizi kaybedip kaybetmeyeceğinizi merak edebilirsiniz. Dokümantasyon, paydaşların sistemi anlamalarına yardımcı olur ve yeni fikirleri teşvik eder. Ve mevcut bir sistem için yeni fikirler, mevcut işinizi sürdürmek için iyi bir ön koşuldur.
Geliştiriciler genellikle aşırı yüklenmekten ve belge yazmaya zaman bulamamaktan şikayetçidir. Öte yandan, iyi belgelerle açıklamaları gerekmeyen şeyleri diğer ekip üyelerine açıklamak için çok zaman harcıyorlar. Ve eğer takıma takviye katılırsa ve herhangi bir belge yoksa, yeni takım üyesi hızla hayal kırıklığına uğrayacak ve tekrar ayrılacaktır.
Dokümantasyonu olmayan sistemler hızla kırmızı bayrakla işaretlenir. Tecrübelerime göre, farklı sistemlerin envanteri en az iki yılda bir yapılıyordu. Sistemin neyden sorumlu olduğunu, nasıl çalıştığını, ne gibi katma değer sağladığını kimse açıklayamıyorsa bu genellikle sistemin ve ekibin geleceği açısından kötü olur. Başkalarının sistemin ne yaptığını bilmediği için onu kapatmaktan korktuğu bir sistemin hayatta kalması nadirdir.
Bazen belgeleme yazmanın önündeki engel, yalnızca mimari belgeleme için değil, alışkanlık eksikliği ve yüksek bilişsel yükün bir karışımıdır. Bunu uzun süredir yapmadıysanız, mevcut bir yazılım değişikliğinin parçası olacak uygun belgeleri kendiliğinden eklemek zordur. Çok az yapı veya çok fazla biçimcilik, yazarların ek bölümler yazmaya veya yeni diyagramlar oluşturmaya odaklanmak yerine, olayların dışında çok fazla düşünmesi gerektiği anlamına gelir. Dokümantasyon, güncel değilse, yazılım mimarları ve diğer paydaşlar arasında her zaman popüler değildir. Hala aktif olarak kullanabilir, geleceğin sigortası olarak reklamını yapabilir ve basit olanaklar ve araçlarla bakımını basitleştirebilirsiniz. Aynı zamanda iyi bir örnek oluşturmanıza ve sahiplerle istişarede bulunarak not almanıza yardımcı olur. Bilgi sahipleriyle görüşmenizi, belgeleri kendiniz uyarlamanızı ve bilgi sahiplerinden değişiklikleri düzeltmelerini istemenizi öneririm. Bu aynı zamanda belgelere olan takdirinizi de gösterir.
Falk Sippach: Çeşitli sebepler var. Bir yandan geliştiriciler bazen neyi, ne ölçüde ve hangi biçimde belgelemeleri gerektiği konusunda kararsız olabiliyorlar. Hedef kitleyi yeterince düşünmezseniz ve içeriği güncel tutmazsanız dokümanlar okunmayacaktır. Bu da onları yazma motivasyonunu azaltıyor. Çoğu zaman diğer konular daha önemlidir, ancak dokümantasyonun önemi çok düşüktür. Son olarak, tipik dokümantasyon araçları günlük işlerden çok uzakta olduğundan, özellikle geliştiriciler için engeller gereksiz derecede yüksektir.
Gernot Starke: Kodlama ve teknik görevler artık daha eğlenceli. Ancak bu eğlenceli faktörü göz ardı edelim: Bazen ekipler, neyin ve hangi derinlikte belgelenmesi gerektiği tam olarak açık olmasa da, “Bir şeyi belgeleyin” genel isteğini alır. Daha da kötüsü: belgelemenin hedef grubu genellikle isimsiz kalıyor ve hiç kimse “çöp için” belgelemeyi sevmiyor. Bir geliştirici olarak benim için belirli bir kişi için belirli bir şey yarattığım netse, “Zaten bunu kimse okumayacak” diye düşündüğümden çok daha fazla motive olurum.
Popüler olmamanın üçüncü nedeni yüksek çaba ve formalite olabilir: Benim düşünceme göre özellikle UML veya SysML modelleme araçlarının kullanılabilirliği zayıftır, dolayısıyla dokümantasyon, Draw.io gibi hafif araçlarla karşılaştırıldığında bir kabus gibi görünür. Son fakat bir o kadar da önemlisi, eğer mevcut dokümantasyon kötüyse veya güncelliğini kaybetmişse ya da wiki'deki ağaçlara göre ormanı artık göremiyorsanız dokümantasyon hiç eğlenceli değildir.
(Resim: Unsplash'ta İltun Hüseyinli)
30 Eylül'deki BetterCode() ArchDoc çevrimiçi konferansı da modern ve basit yazılım mimarisini belgelemeye odaklanıyor. Konuşmacılar arasında burada röportaj yapılan Charlotte Scharbert, Alexander Schwartz ve Gernot Starke yer alırken, Falk Sippach da danışma kurulu üyesi olarak programın şekillenmesine yardımcı oldu.
8 Eylül'e kadar erken rezervasyon yaptıranlara indirim uygulanmaktadır.
Haberin Sonu
Duyuru
Yazılım dokümantasyonu sinir bozucu olabilir, ancak böyle olması gerekmez. iX dört uzmana deneyimlerini ve iyileştirme önerilerini sordu. Charlotte Scharbert, Alexander Schwartz, Falk Sippach ve Dr. Gernot Starke, yapay zeka araçlarının şu anda ne kadar kullanışlı olduğu, geliştiricilerin kullanabileceği en iyi uygulamalar, hangi tuzaklardan kaçınmaları gerektiği ve dokümantasyonun günlük işlere nasıl sorunsuz bir şekilde entegre edilebileceği hakkında bilgiler veriyor.
Başlangıçta yazılım geliştirme alanında çalışan Charlotte, daha sonra dokümantasyon alanına geçti ve şu anda teknik dokümantör olarak çalışıyor. Amaçları yazılım dokümantasyonu konusunu daha popüler hale getirmek ve dokümantasyonun zaman alıcı ve sinir bozucu olmak zorunda olmadığını göstermektir.
Alexander Schwartz, Red Hat'te Keycloak projesinde baş yazılım mühendisi ve bakım sorumlusu olarak çalışıyor ve aynı zamanda yazılım mimarı ve BT danışmanı olarak deneyime sahip. Ayrıca özel olarak IntelliJ için AsciiDoc eklentisi de dahil olmak üzere açık kaynaklı yazılımlar geliştiriyor. Konferanslarda ve kullanıcı gruplarında Java, Kubernetes, performans, iyi dokümantasyon, kimlik ve erişim yönetimi hakkında konuşuyor.
Falk Sippach, embarc Software Consulting GmbH'de yazılım mimarı, danışman ve eğitmendir. Java topluluğuna dahil olup bilgilerini makalelerde, blog yazılarında ve konuşmalarda paylaşmaktadır.
INNOQ Üyesi Dr. Gernot Starke, yazılım geliştirme ve mimari alanında koç ve danışman olarak çalışmaktadır. Arc42 ve Goal42 açık kaynak projelerinin kurucu ortağı ve sürdürücüsüdür, kitapların yazarıdır ve konferanslarda ara sıra konuşmacıdır.
Yaygın engeller: takdir eksikliği, net olmayan hedef gruplar ve talimatlar
iX: Yazılımın ve mimarisinin belgelenmesi pek popüler olmadığı yönünde bir üne sahiptir. Sizce en büyük engeller neler?
Charlotte Schabert: Bence büyük bir sorun, ev planları için mimaride veya elektrik mühendisliğinde kablo şemaları için olduğu gibi bunun için bir standart olmamasıdır. Elbette UML gibi standartlarımız var, ancak bunlar nadiren kullanılıyor ve deneyimlerime göre yazılım mimarisini temsil etmeye yalnızca kısmen uygun. Bu nedenle, genellikle birkaç ay sonra kimsenin gerçekten anlamadığı “kutu ve çizgiler”den oluşan kafa karıştırıcı bir düzenlemeyle karşılaşırsınız veya proje belgelerinde Google aramasından alınan bir resimle birlikte “altıgen bir mimari kullanıyoruz” yazıyor – hepsi bu. Dokümantasyon genellikle yalnızca projenin sonunda oluşturulur. O zaman her şeyi hatırlamak veya bir şeyin nasıl yapılandırıldığını anlamak zordur. Bu, dokümantasyonu sıkıcı ve sinir bozucu hale getirir.
Ayrıca, hızlı ve kolay bir şekilde, değişiklik yapılması durumunda daha sonra kolayca düzenlenebilecek diyagramlar oluşturabileceğiniz bazı araçlar da vardır. Deneyimlerime göre, grafiksel araçlar hızla hayal kırıklığına neden oluyor çünkü geliştiriciler kutuları sonsuza kadar taşımak istemiyor. “Kod olarak diyagramlar” iyi bir yaklaşım, ancak bence henüz tam potansiyeline ulaşmadı.
Alexander Schwartz: Dokümantasyona yönelik algılanan takdir eksikliği yaygın bir engeldir. Belgelerin aktif olarak okunduğunu ve kullanıldığını görmezlerse geliştiriciler arasında her zaman popüler değildir. Başlayabileceğiniz yer burasıdır: Bir web izleme aracı, belgelerin hangi bölümlerine ve ne sıklıkta erişildiğini gösterebilir; önlenebilir müşteri taleplerine ilişkin istatistikler ise belgelerin nerede eksik olduğunu gösterebilir. Bir yazılım mimarı veya işletme departmanı, belgeleri okuyarak ve söz konusu sistemi anlamak için sorular sorarak, belgelere olan takdirlerini gösterebilir. Örneğin, bir planlama toplantısına en son ne zaman bir belgeden bir alıntı veya grafik getirdiğinizi ve diyagramı kağıtlı sunum tahtası üzerinde yeniden çizmek yerine bunun üzerinde aktif olarak çalıştığınızı kendinize sorabilirsiniz. Belgeleme geleceğe bir yatırım olabilir, ancak bazen tam tersi olarak algılanır: Çok fazla belgelemeniz durumunda işinizi kaybedip kaybetmeyeceğinizi merak edebilirsiniz. Dokümantasyon, paydaşların sistemi anlamalarına yardımcı olur ve yeni fikirleri teşvik eder. Ve mevcut bir sistem için yeni fikirler, mevcut işinizi sürdürmek için iyi bir ön koşuldur.
Geliştiriciler genellikle aşırı yüklenmekten ve belge yazmaya zaman bulamamaktan şikayetçidir. Öte yandan, iyi belgelerle açıklamaları gerekmeyen şeyleri diğer ekip üyelerine açıklamak için çok zaman harcıyorlar. Ve eğer takıma takviye katılırsa ve herhangi bir belge yoksa, yeni takım üyesi hızla hayal kırıklığına uğrayacak ve tekrar ayrılacaktır.
Dokümantasyonu olmayan sistemler hızla kırmızı bayrakla işaretlenir. Tecrübelerime göre, farklı sistemlerin envanteri en az iki yılda bir yapılıyordu. Sistemin neyden sorumlu olduğunu, nasıl çalıştığını, ne gibi katma değer sağladığını kimse açıklayamıyorsa bu genellikle sistemin ve ekibin geleceği açısından kötü olur. Başkalarının sistemin ne yaptığını bilmediği için onu kapatmaktan korktuğu bir sistemin hayatta kalması nadirdir.
Bazen belgeleme yazmanın önündeki engel, yalnızca mimari belgeleme için değil, alışkanlık eksikliği ve yüksek bilişsel yükün bir karışımıdır. Bunu uzun süredir yapmadıysanız, mevcut bir yazılım değişikliğinin parçası olacak uygun belgeleri kendiliğinden eklemek zordur. Çok az yapı veya çok fazla biçimcilik, yazarların ek bölümler yazmaya veya yeni diyagramlar oluşturmaya odaklanmak yerine, olayların dışında çok fazla düşünmesi gerektiği anlamına gelir. Dokümantasyon, güncel değilse, yazılım mimarları ve diğer paydaşlar arasında her zaman popüler değildir. Hala aktif olarak kullanabilir, geleceğin sigortası olarak reklamını yapabilir ve basit olanaklar ve araçlarla bakımını basitleştirebilirsiniz. Aynı zamanda iyi bir örnek oluşturmanıza ve sahiplerle istişarede bulunarak not almanıza yardımcı olur. Bilgi sahipleriyle görüşmenizi, belgeleri kendiniz uyarlamanızı ve bilgi sahiplerinden değişiklikleri düzeltmelerini istemenizi öneririm. Bu aynı zamanda belgelere olan takdirinizi de gösterir.
Falk Sippach: Çeşitli sebepler var. Bir yandan geliştiriciler bazen neyi, ne ölçüde ve hangi biçimde belgelemeleri gerektiği konusunda kararsız olabiliyorlar. Hedef kitleyi yeterince düşünmezseniz ve içeriği güncel tutmazsanız dokümanlar okunmayacaktır. Bu da onları yazma motivasyonunu azaltıyor. Çoğu zaman diğer konular daha önemlidir, ancak dokümantasyonun önemi çok düşüktür. Son olarak, tipik dokümantasyon araçları günlük işlerden çok uzakta olduğundan, özellikle geliştiriciler için engeller gereksiz derecede yüksektir.
Gernot Starke: Kodlama ve teknik görevler artık daha eğlenceli. Ancak bu eğlenceli faktörü göz ardı edelim: Bazen ekipler, neyin ve hangi derinlikte belgelenmesi gerektiği tam olarak açık olmasa da, “Bir şeyi belgeleyin” genel isteğini alır. Daha da kötüsü: belgelemenin hedef grubu genellikle isimsiz kalıyor ve hiç kimse “çöp için” belgelemeyi sevmiyor. Bir geliştirici olarak benim için belirli bir kişi için belirli bir şey yarattığım netse, “Zaten bunu kimse okumayacak” diye düşündüğümden çok daha fazla motive olurum.
Popüler olmamanın üçüncü nedeni yüksek çaba ve formalite olabilir: Benim düşünceme göre özellikle UML veya SysML modelleme araçlarının kullanılabilirliği zayıftır, dolayısıyla dokümantasyon, Draw.io gibi hafif araçlarla karşılaştırıldığında bir kabus gibi görünür. Son fakat bir o kadar da önemlisi, eğer mevcut dokümantasyon kötüyse veya güncelliğini kaybetmişse ya da wiki'deki ağaçlara göre ormanı artık göremiyorsanız dokümantasyon hiç eğlenceli değildir.
(Resim: Unsplash'ta İltun Hüseyinli)
30 Eylül'deki BetterCode() ArchDoc çevrimiçi konferansı da modern ve basit yazılım mimarisini belgelemeye odaklanıyor. Konuşmacılar arasında burada röportaj yapılan Charlotte Scharbert, Alexander Schwartz ve Gernot Starke yer alırken, Falk Sippach da danışma kurulu üyesi olarak programın şekillenmesine yardımcı oldu.
8 Eylül'e kadar erken rezervasyon yaptıranlara indirim uygulanmaktadır.
Haberin Sonu