(Bu röportaj Almanca olarak da mevcuttur.)
Duyuru
Yazılım dokümantasyonu sıkıntılı olabilir ancak böyle olması gerekmiyor. iX, deneyimlerini paylaşan ve belgeleme sürecini iyileştirmeye yönelik öneriler sunan dört uzmanla konuştu. Charlotte Scharbert, Alexander Schwartz, Falk Sippach ve Gernot Starke, yapay zeka araçlarının yararlı olup olamayacağını, geliştiricilerin hangi en iyi uygulamaları uygulayabileceğini, hangi olası tuzaklardan kaçınmaları gerektiğini ve belgeleri günlük iş akışlarına sorunsuz bir şekilde nasıl entegre edebileceklerini değerlendiriyor.
Başlangıçta yazılım geliştirme alanında çalışan Charlotte Scharbert, dokümantasyon alanına geçti ve şu anda teknik dokümantör olarak çalışıyor. Amacı, yazılım dokümantasyonunu daha popüler hale getirmek ve dokümantasyonun sıkıcı ve zaman alıcı olması gerekmediğini göstermektir.
Alexander Schwartz, Red Hat'te Keycloak projesinde Baş Yazılım Mühendisi ve Bakımcısı olarak çalışıyor ve aynı zamanda yazılım mimarı ve BT danışmanı olarak deneyime sahip. Boş zamanlarında 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ğitmen olarak çalışmaktadır. 15 yılı aşkın süredir Java ortamında ağırlıklı olarak çevik yazılım geliştirme projelerini desteklemektedir. Java topluluğunun aktif bir üyesi olarak, bilgilerini makalelerde ve blog yazılarında paylaşmaktan ve konferanslarda konuşmacı olarak bulunmaktan keyif almaktadı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ü olmasının yanı sıra kitap yazarı ve ara sıra konferans konuşmacısı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 değildir. Görüşünüze ve deneyiminize göre en büyük engeller neler?
Charlotte Schabert: Bence temel sorunlardan biri, mimaride kat planları veya elektrik mühendisliğinde bağlantı şemaları için mevcut olana benzer bir standardın bulunmaması. Elbette UML gibi standartlarımız var, ancak bunlar nadiren kullanılıyor ve benim deneyimime göre yazılım mimarisinin haritalandırılmasına yalnızca sınırlı bir ölçüde uygundur. Sonuç olarak, genellikle birkaç ay sonra kimsenin gerçekten anlamadığı, kafa karıştırıcı bir kutu ve çizgi düzenlemesi bulursunuz veya proje belgelerinde Google aramasından alınan bir resimle birlikte “altıgen bir mimari kullanıyoruz” ifadesi yer alır ve hepsi bu. Dokümantasyon genellikle yalnızca projenin sonunda oluşturulur. O zaman her şeyi hatırlamak ya da bir şeyin nasıl inşa edildiğini yeniden yapılandırmak elbette zordur. Bu, dokümantasyonu sıkıcı ve sinir bozucu hale getirir. Ayrıca, bir şeyler değiştiğinde kolayca uyarlanabilecek diyagramları hızlı ve kolay bir şekilde oluşturmak için yalnızca birkaç araç vardır. Deneyimlerime göre, grafiksel araçlar sinir bozucu olma eğilimindedir çünkü geliştiriciler kutuları taşımak için uzun süre harcamak istemezler. Kod olarak diyagramlar bu durumda iyi bir yaklaşım, ancak bana göre henüz tam potansiyeline ulaşmadı.
Alexander Schwartz: Dokümantasyona yönelik algılanan takdir eksikliği yaygın bir engeldir. Geliştiriciler, aktif olarak okunduğunu ve kullanıldığını görmedikleri dokümantasyonu her zaman sevmezler. Bu iyi bir başlangıç noktasıdır: Bir web izleme aracı, belgelerin hangi bölümlerine ve ne sıklıkta erişildiğini gösterebilir; kaçınılabilir müşteri sorularına ilişkin istatistikler ise belgelerin nerede eksik olduğunu gösterebilir. Bir yazılım mimarı veya uzman departman, dokümantasyonu okuyup, söz konusu sistemi anlamak için sorular sorarak dokümantasyonu takdir ettiğini gösterebilir. Örneğin, bir planlama toplantısına en son ne zaman bir dokümantasyondan alıntı veya mevcut bir diyagram getirdiğinizi ve diyagramı kağıtlı sunum tahtası üzerinde yeniden çizmek yerine onunla aktif olarak çalıştığınızı kendinize sorabilirsiniz. Belgeleme geleceğe yapılan bir yatırım olabilir, ancak bazen tam tersi olarak algılanır: geliştiriciler çok fazla belgelemeleri durumunda işlerini kaybetmekten korkabilirler. Buna karşılık, dokümantasyon paydaşların sistemi anlamalarına yardımcı olur ve yeni fikirleri teşvik eder; mevcut bir sistem için yeni fikirler ise mevcut çalışmanızı sürdürmenin iyi bir yoludur.
Geliştiriciler sıklıkla aşırı çalışmaktan ve dokümantasyon yazmaya zaman bulamamaktan şikayetçidir. Bunun yerine, eğer iyi bir dokümantasyon olsaydı açıklamak zorunda kalmayacakları şeyleri başkalarına açıklamak için çok zaman harcıyorlar. Takviyeler ekibe katıldığında ve herhangi bir belge bulunmadığında, yeni ekip üyesi kısa sürede hayal kırıklığına uğrayabilir ve ayrılabilir.
Ayrıca dokümantasyonu olmayan sistemlerin kesilme riski yüksektir. Deneyimlerime göre, farklı sistemlerin envanteri en fazla 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 zararlıdır. Ancak nadir durumlarda böyle bir sistem, başkalarının bilinmeyen sonuçlar nedeniyle onu kapatmaktan çok korkması nedeniyle hayatta kalacaktır.
Bazen alışkanlık eksikliği ve yüksek bilişsel yük birleşince, yalnızca mimari belgeleme değil, belgeleme yazmanın da önünde engel olabiliyor. Bunu uzun süredir yapmadıysanız, mevcut bir yazılım değişikliğinin parçası olabilecek uygun belgeleri kendiliğinden eklemek zordur. Çok az yapı ve hatta çok fazla formalizm, yazarların ek bölümleri yazmaya veya yeni diyagramı oluşturmaya odaklanmak yerine ayrıntılar hakkı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. Ancak bunu aktif olarak kullanabilir, geleceğin sigortası olarak tanıtabilir ve basit tesis ve araçlarla bakımı basitleştirebilirler. Belgelerin sahiplerinin de aynı fikirde olması durumunda örnek olmak ve kişisel olarak katkıda bulunmak da faydalıdır. Bilgi sahibi kişilerle görüşmenizi, belgeleri uyarlamanızı ve ardından onlardan değişiklikleri düzeltmelerini istemenizi öneririm. Bu aynı zamanda belgelere olan takdirinizi de gösterir.
Falk Sippach: Bunun birkaç nedeni var. Bir yandan geliştiriciler neyi, ne ölçüde ve hangi biçimde belgeleyeceklerini her zaman bilemiyorlar. Ayrıca hedef kitleye yeterince önem verilmemesi ve içeriğin güncel tutulmaması durumunda dokümanlar okunmayarak kazançlı çıkar. Bu da yazma motivasyonunu azaltıyor. Ayrıca diğer konular genellikle daha önemliyken, dokümantasyonun önemi çok düşüktür. Son olarak, tipik dokümantasyon araçları günlük işlerden çok uzaktır, bu da özellikle geliştiriciler için engelleri gereksiz derecede yüksek hale getirir.
Gernot Starke: Kodlama ve teknik görevler artık daha eğlenceli. Ancak bu eğlenceli faktörün yanı sıra: Ekipler bazen “bir şeyi belgelemek” için spesifik olmayan bir talep alırken, tam olarak neyi belgelemeleri ve hangi derinlikte belgelemeleri gerektiği açık değildir. Daha da kötüsü: belgelemenin hedef grubu genellikle belirtilmez ve hiç kimse kendini boşuna belgelemekten hoşlanmaz. Bir geliştirici olarak benim için belirli bir ABC çalışanına özel bir şey yarattığım açıksa, “zaten bunu kimse okumayacak” diye düşünmekten çok daha fazla motive olurum.
Popüler olmamanın üçüncü nedeni yüksek çaba ve formalizm olabilir: Bana göre, özellikle UML ve SysML modelleme araçlarının kullanılabilirliği bir dereceye kadar zayıf olabilir, bu da dokümantasyonun Draw.io gibi hafif araçlarla karşılaştırıldığında bir kabus gibi görünmesine neden olabilir. Son fakat bir o kadar da önemlisi, eğer mevcut dokümantasyon zayıf veya güncel değilse ya da Wiki gereksiz bilgilerle aşırı yüklenmişse, dokümantasyon yapmak eğlenceli değildir.
Haberin Sonu
Duyuru
Yazılım dokümantasyonu sıkıntılı olabilir ancak böyle olması gerekmiyor. iX, deneyimlerini paylaşan ve belgeleme sürecini iyileştirmeye yönelik öneriler sunan dört uzmanla konuştu. Charlotte Scharbert, Alexander Schwartz, Falk Sippach ve Gernot Starke, yapay zeka araçlarının yararlı olup olamayacağını, geliştiricilerin hangi en iyi uygulamaları uygulayabileceğini, hangi olası tuzaklardan kaçınmaları gerektiğini ve belgeleri günlük iş akışlarına sorunsuz bir şekilde nasıl entegre edebileceklerini değerlendiriyor.
Başlangıçta yazılım geliştirme alanında çalışan Charlotte Scharbert, dokümantasyon alanına geçti ve şu anda teknik dokümantör olarak çalışıyor. Amacı, yazılım dokümantasyonunu daha popüler hale getirmek ve dokümantasyonun sıkıcı ve zaman alıcı olması gerekmediğini göstermektir.
Alexander Schwartz, Red Hat'te Keycloak projesinde Baş Yazılım Mühendisi ve Bakımcısı olarak çalışıyor ve aynı zamanda yazılım mimarı ve BT danışmanı olarak deneyime sahip. Boş zamanlarında 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ğitmen olarak çalışmaktadır. 15 yılı aşkın süredir Java ortamında ağırlıklı olarak çevik yazılım geliştirme projelerini desteklemektedir. Java topluluğunun aktif bir üyesi olarak, bilgilerini makalelerde ve blog yazılarında paylaşmaktan ve konferanslarda konuşmacı olarak bulunmaktan keyif almaktadı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ü olmasının yanı sıra kitap yazarı ve ara sıra konferans konuşmacısı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 değildir. Görüşünüze ve deneyiminize göre en büyük engeller neler?
Charlotte Schabert: Bence temel sorunlardan biri, mimaride kat planları veya elektrik mühendisliğinde bağlantı şemaları için mevcut olana benzer bir standardın bulunmaması. Elbette UML gibi standartlarımız var, ancak bunlar nadiren kullanılıyor ve benim deneyimime göre yazılım mimarisinin haritalandırılmasına yalnızca sınırlı bir ölçüde uygundur. Sonuç olarak, genellikle birkaç ay sonra kimsenin gerçekten anlamadığı, kafa karıştırıcı bir kutu ve çizgi düzenlemesi bulursunuz veya proje belgelerinde Google aramasından alınan bir resimle birlikte “altıgen bir mimari kullanıyoruz” ifadesi yer alır ve hepsi bu. Dokümantasyon genellikle yalnızca projenin sonunda oluşturulur. O zaman her şeyi hatırlamak ya da bir şeyin nasıl inşa edildiğini yeniden yapılandırmak elbette zordur. Bu, dokümantasyonu sıkıcı ve sinir bozucu hale getirir. Ayrıca, bir şeyler değiştiğinde kolayca uyarlanabilecek diyagramları hızlı ve kolay bir şekilde oluşturmak için yalnızca birkaç araç vardır. Deneyimlerime göre, grafiksel araçlar sinir bozucu olma eğilimindedir çünkü geliştiriciler kutuları taşımak için uzun süre harcamak istemezler. Kod olarak diyagramlar bu durumda iyi bir yaklaşım, ancak bana göre henüz tam potansiyeline ulaşmadı.
Alexander Schwartz: Dokümantasyona yönelik algılanan takdir eksikliği yaygın bir engeldir. Geliştiriciler, aktif olarak okunduğunu ve kullanıldığını görmedikleri dokümantasyonu her zaman sevmezler. Bu iyi bir başlangıç noktasıdır: Bir web izleme aracı, belgelerin hangi bölümlerine ve ne sıklıkta erişildiğini gösterebilir; kaçınılabilir müşteri sorularına ilişkin istatistikler ise belgelerin nerede eksik olduğunu gösterebilir. Bir yazılım mimarı veya uzman departman, dokümantasyonu okuyup, söz konusu sistemi anlamak için sorular sorarak dokümantasyonu takdir ettiğini gösterebilir. Örneğin, bir planlama toplantısına en son ne zaman bir dokümantasyondan alıntı veya mevcut bir diyagram getirdiğinizi ve diyagramı kağıtlı sunum tahtası üzerinde yeniden çizmek yerine onunla aktif olarak çalıştığınızı kendinize sorabilirsiniz. Belgeleme geleceğe yapılan bir yatırım olabilir, ancak bazen tam tersi olarak algılanır: geliştiriciler çok fazla belgelemeleri durumunda işlerini kaybetmekten korkabilirler. Buna karşılık, dokümantasyon paydaşların sistemi anlamalarına yardımcı olur ve yeni fikirleri teşvik eder; mevcut bir sistem için yeni fikirler ise mevcut çalışmanızı sürdürmenin iyi bir yoludur.
Geliştiriciler sıklıkla aşırı çalışmaktan ve dokümantasyon yazmaya zaman bulamamaktan şikayetçidir. Bunun yerine, eğer iyi bir dokümantasyon olsaydı açıklamak zorunda kalmayacakları şeyleri başkalarına açıklamak için çok zaman harcıyorlar. Takviyeler ekibe katıldığında ve herhangi bir belge bulunmadığında, yeni ekip üyesi kısa sürede hayal kırıklığına uğrayabilir ve ayrılabilir.
Ayrıca dokümantasyonu olmayan sistemlerin kesilme riski yüksektir. Deneyimlerime göre, farklı sistemlerin envanteri en fazla 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 zararlıdır. Ancak nadir durumlarda böyle bir sistem, başkalarının bilinmeyen sonuçlar nedeniyle onu kapatmaktan çok korkması nedeniyle hayatta kalacaktır.
Bazen alışkanlık eksikliği ve yüksek bilişsel yük birleşince, yalnızca mimari belgeleme değil, belgeleme yazmanın da önünde engel olabiliyor. Bunu uzun süredir yapmadıysanız, mevcut bir yazılım değişikliğinin parçası olabilecek uygun belgeleri kendiliğinden eklemek zordur. Çok az yapı ve hatta çok fazla formalizm, yazarların ek bölümleri yazmaya veya yeni diyagramı oluşturmaya odaklanmak yerine ayrıntılar hakkı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. Ancak bunu aktif olarak kullanabilir, geleceğin sigortası olarak tanıtabilir ve basit tesis ve araçlarla bakımı basitleştirebilirler. Belgelerin sahiplerinin de aynı fikirde olması durumunda örnek olmak ve kişisel olarak katkıda bulunmak da faydalıdır. Bilgi sahibi kişilerle görüşmenizi, belgeleri uyarlamanızı ve ardından onlardan değişiklikleri düzeltmelerini istemenizi öneririm. Bu aynı zamanda belgelere olan takdirinizi de gösterir.
Falk Sippach: Bunun birkaç nedeni var. Bir yandan geliştiriciler neyi, ne ölçüde ve hangi biçimde belgeleyeceklerini her zaman bilemiyorlar. Ayrıca hedef kitleye yeterince önem verilmemesi ve içeriğin güncel tutulmaması durumunda dokümanlar okunmayarak kazançlı çıkar. Bu da yazma motivasyonunu azaltıyor. Ayrıca diğer konular genellikle daha önemliyken, dokümantasyonun önemi çok düşüktür. Son olarak, tipik dokümantasyon araçları günlük işlerden çok uzaktır, bu da özellikle geliştiriciler için engelleri gereksiz derecede yüksek hale getirir.
Gernot Starke: Kodlama ve teknik görevler artık daha eğlenceli. Ancak bu eğlenceli faktörün yanı sıra: Ekipler bazen “bir şeyi belgelemek” için spesifik olmayan bir talep alırken, tam olarak neyi belgelemeleri ve hangi derinlikte belgelemeleri gerektiği açık değildir. Daha da kötüsü: belgelemenin hedef grubu genellikle belirtilmez ve hiç kimse kendini boşuna belgelemekten hoşlanmaz. Bir geliştirici olarak benim için belirli bir ABC çalışanına özel bir şey yarattığım açıksa, “zaten bunu kimse okumayacak” diye düşünmekten çok daha fazla motive olurum.
Popüler olmamanın üçüncü nedeni yüksek çaba ve formalizm olabilir: Bana göre, özellikle UML ve SysML modelleme araçlarının kullanılabilirliği bir dereceye kadar zayıf olabilir, bu da dokümantasyonun Draw.io gibi hafif araçlarla karşılaştırıldığında bir kabus gibi görünmesine neden olabilir. Son fakat bir o kadar da önemlisi, eğer mevcut dokümantasyon zayıf veya güncel değilse ya da Wiki gereksiz bilgilerle aşırı yüklenmişse, dokümantasyon yapmak eğlenceli değildir.
Haberin Sonu