Açık kaynak bir araç kullanmayı planlıyorsam, önce bu aracın web sayfasını açıp linkinden benim konfigürasyonuma en uygun olanı bulur ve aracı indiririm. Ardından ana sayfa da bu aracı varolan sisteme nasıl entegre edeceğime dair bir doküman ararım. Genelde “Installation Guide”, “How to Configure” veya “Get Started” linkleridir bu ve bunu adım adım takip ederek entegrasyonu yaparım. Yaptığım entegrasyon işinde bana yardımcı olan bu dokümanlar, çoğunlukla bir Wiki aracı ile yapılmış olur. Ama sonuçta orada bir doküman vardır ve her zaman “güle güle ve dokümanlar için teşekkürler” diyecek bir sebep ortaya çıkar.
Hadi bakim ye yemeğini, yoksa sana Dokümantasyon yapma cezası veririm...
Fakat çoğu zaman doküman hazırlamak hem iş analistleri için, hem de kod geliştiriciler için bir eziyet haline gelir. Bunun sebebi ise gerek projenin geliştirilmesi esnasında zaman ile ilgili sıkıntıların olması, gerekse dokümantasyonun zaman zaman gereksiz olarak nitelendirilmesidir. Ama bu düşüncelerin aksine, dokümantasyon doğru yapıldığı takdirde kod geliştirme sürecini hızlandırır. Hele proje ekibinde rotasyon veya sirkülasyon söz konusu ise dokümantasyon hayat kurtarabilir.
Diyelim ki kabul ettim neyi dokümante edeceğim ?
Neyi dokümante etmeyeceğiz ki? Merak etmeyin, istenildiğinde dokümante edilmeyecek hiçbirşey yoktur. Ama ben yine de birkaç örnek vermeye çalışayım. Önce yazdığımız kod kümelerinin ne iş yaptığı ile ilgili birer cümlecik yorumlar yazabiliriz. Metodun ne iş yaptığı, ne zaman ve kim tarafından yazıldığı ile ilgili küçük birkaç cümle zamanı geldiğinde hayat kurtaracaktır. Ya da projede daha önce kimsenin kullanmadığı bir API kullandığımızı varsayalım. Bunu nasıl kodumuza entegre ettiğimizi dokümante edersek, ileride aynı entegrasyonu yapmak isteyen başka bir developer zorlanmayacak ve üstüne üstlük bize dua edecektir. Bu da önemli bir dokümantasyondur. Devam edelim, mesela bir modülde aktif olarak çalışıyoruz, hazırladığımız bir önyüz var, bu önyüzü dokümante edebiliriz, bunun bir süre sonra bize zaman kazandırdığını fark edeceğiz. Bunlar kod geliştirenlerin yapabileceği dokümantasyona küçük, basit örnekler.
Ama sadece onlar mı dokümantasyon yapacak? Kesinlikle hayır. Konfigürasyon ve Sürüm Yönetimi ile uğraşıyorsanız, dokümantasyonunuz hayati önem arz eder. Mesela, yazılan projenin değişik safhalarının tutulduğu (DEV, ALFA, BETA gibi) değişik ortamlar vardır. Bu ortamların konfigürasyonları değişiklik gösterebilir. Bunlar dokümante edilirse, kod geliştiren arkadaşlar için çok yararlı bir kaynak olur. Veya, projenin geliştirilmesi, sürümün yönetilmesi, kodların tutulması ve sistemin çalışması ile ilgili kullanılan tüm araçların hangi versiyonlarının kullanıldığı bir doküman hazırlarsak, bu hem bizim için, hem de projenin diğer parçalarında çalışan arkadaşlar için çok yararlı, ekstra telefonları engelleyen bir hizmet haline gelir.
Evet dokümantasyon bir hizmettir. Bizim Gözümüzden Açık Kaynak adlı yazımda da belirttiğim gibi, açık kaynağın para kazandığı hizmetlerden birisi Dokümantasyondur..
Dokümantasyon yapmak için araç var mı araç? Olmamııı...
Peki nasıl yapacağız bu dokümantasyonu? Nasıl yapacağız sorusunun cevabını başkaları nasıl yapıyor sorusundan çıkan cevap ile karşılayabiliriz. Sun dokümantasyon sayfalarını wiki tabanlı bir uygulama olan Confluence üzerinden yayınlıyor. Bununla ilgili güzel bir klibi Sun ve Wiki adlı yazımdan izleyebilirsiniz. Confluence ile ilgili güzel bir yazıyı da bu linkte bulabilirsiniz. Wikipedia dünyanın en büyük ansiklopedisi yine wiki motoru üzerine kurulu. O halde sanırım sorumuzun cevabı wiki motorları. Wiki motorları ile ilgili (tarih olarak biraz eski olsa da) güzel bir karşılaştırmayı Which Open Source Wiki Works For You yazısından bulabilirsiniz. Ya da Open Source Wiki Engines in Java linkinde diğer alternatifleri bulabilirsiniz.
İnceleyebildiğim kadarı ile bunlar içinde dört tane ürün ön plana çıkıyor, bunların başında Confluence geliyor, diğer üç alternatif ise Twiki (Kullanım yaygınlığı açısından), PmWiki (kurulum kolaylığı açısından), MediaWiki (en.wikipedia.org'un alt yapısı olması açısından, ya da Gönenç'in eklemesi ile Alfresco'nun da altyapısı)..
Confluence ile ilgili birkaç kelime yazmak gerekirse, kurulumu gerçekten kolay bir araç. Birkaç adım ve kurulum sihirbazı ile herşeyi rahatlıkla halledebiliyorsunuz, kişisel kullanmak isterseniz, siteden kişisel lisans talep ediyorsunuz, ardından elinizin altında 2 kayıtlı kullanıcı sahibi olan ücretsiz bir Confluence aracınız oluyor. Eğer gerekli lisans ücretini öderseniz 50, 500 veya sınırsız kullanıcı ile bir Confluence'ınız olur. Lisans ücreti de çok fazla değil ($2200, $4000 veya $8000). Ama diğer tüm wiki motorlarının ücretsiz olduğunu varsayarsak pahalı diyebiliriz. Bu nedenle ben daha çok Twiki üzerine yoğunlaştım, ve nihayetinde Twiki'yi hayata geçirdim. Twiki'nin kurulumu ve hayata geçirilmesi esnasında yaptıklarımı, karşılaştığım sorunları bir sonraki yazımda detaylı olarak yazacağım.
Son olarak belirtmekte çok büyük fayda var, kod geliştiren arkadaşlar, sistemi yöneten arkadaşlar ve son kullanıcılar arasında iletişimi en iyi sağlayan şey iyi kullanılan, interaksiyon içeren wiki sayfalarıdır.
2 comments:
Oğuz, Dünkü Sun ve Confluence yazındaki film beni üniversite hazırlık yıllarımda kütüphanede Kernegie and Ritchie'nin programlama kitabına götürdü. Yaklaşık 20 yıl önceye! Yanılmıyorsam o kitabın bir yerinde typesetting'in kendileri tarafından yapıldığını özellikle belirtiyorlardı. Demek ki iyi bir doküman yazmak ile dönemin en iyi C kitabını yazmak aynı kefede... Bugün bu işler wiki araçları ile çok kolay yapılabilirken, paylaşım (sharing) ve etkileşimli olarak çalışma (collaboration) konusunda sınırlar da ortadan kalkıyor. Bugün ben dahil herkes bilginin paylaşımının en etkin yöntemlerinden birisinin wiki olduğunu düşünüyor.
Bence wikini sağladığı en önemli avantaj doküman yazmanaın sıkıcı bir şey olmasını değiştirmiş olması. Düşünsenize bir dokümana başlıyoruz; ben en iyi bildiğim kısmı yazıyorum; daha benim düzeltmelerim biter bitmez birileri benim eksiklerimi tamamlıyor.
Teşekkürler Surav,
Senin de belirttiğin gibi, sen yazını bitirir bitirmez başka birisi seni düzeltiyor. Ama hiçbir zaman negatif yönde değil.
Dokümantasyon hazırlamak wiki ile daha paylaşımcı ve daha kreatif bir hal alıyor. Bu da beraberinde daha iyisini ve mükemmelini yazabilme şansını sağlıyor.
Ve bu şansı kullanmak da sanırım bize kalıyor ;)
Post a Comment