Dokümantasyon ve Twiki – II (TWiki)

Aşağıdaki adımları izleyerek RedHat EL3 üzerine Twiki 4.1.2 kurulumunu tamamladım. Twiki'nin çalışabilmesi için Apache ve Perl'ün Linux üzerinde bulunması gerekiyor. Neyse ki, bunlar yüklü, Apache 2.0.46 ve Perl 5.8.0. Hmm bu arada kurulum bir miktar linux bilgisi ve sistem yöneticiliği gerektiriyor, zaman zaman root şifresine ihtiyacınız olacak. Eğer bu tür yeteneklerim yok diyorsanız, VMDebianStable linki işinizi görecektir, kendisi yaklaşık 350 MB. Ben uzak durdum tabi. Şimdi Twiki'yi kurmak için neler gerektiğini sırası ile anlatayım. Anlatım esnasında belirtilen tüm lokasyonlar kurulumu yaptığımız makinenindir.

• Twiki4.1.2 linkinden Twiki'yi indirin. Yaklaşık 5,5 MB.

• /var/www/twiki klasörünün içerisine bu zip'i açın.

• Twiki'nin çalışmasında aksama olmaması için bazı CPAN modüllerinin yüklenmesi lazım. Bu CPAN'ların listesini bu linkte bulabilirsiniz. Bunları tar.gz formatında http://cpan.perl.org/ sitesinden indirip ardından “make” komutu ile yapılandırabilirsiniz. Fakat daha kolayı var, bu linkten RPM'leri indirin, sonra bunları twiki makinesine kopyalayın, sonra bunları kopyaladığınız klasör altında "rpm -ivh *" komutunu çalıştırın. Evet hepsi bu, gerekli tüm CPAN modülleri kuruldu.

• Apache ayarlarının yapılması lazım. Bunun için TwikiApacheConfigGenerator linkine girip, formu doldurmamız gerekiyor. Bu formu doldururken birkaç hususa dikkat etmeniz gerekiyor,

  • Eğer ayarları lokalden yapmayacaksanız, IP listesine IP'nizi ekleyin.

  • Yine konfigürasyon ayarlarını yapacak kullanıcıların listesini kullanıcı listesine ekleyin.

  • Login Manager seçin, sakın none'da bırakmayın. Login sayfası kullanacaksanız, TemplateLogin'i seçin, diğeri zaten anlaşılır. Ben TemplateLogin seçtim.

  • mod_perl'ü enable etmeyin, bunun dışında diğer ayarlara dokunmasanız da olur.

    • No you do not need mod_perl. mod_perl needs to be installed on your Apache installation for you to be able to use it and you need a lot of RAM. mod_perl compiles all the perl code ONCE and keep it in RAM. This speeds up the execution of TWiki by at least factor 2. But mod_perl also keeps all variables in RAM so the programs must be written with great care. The TWiki core and the default plugins are pretty mod_perl safe now. But some other plugins do not work with mod_perl. I recommend to start a new TWiki installation without. And once it works you can try and activate it. Read the topic ModPerlUnix for more information. This ApacheConfigGenerator is a helper that generates a working apache config also for mod_perl but you need to know more about it to use it. As a beginner, run without.

• Update config file dedikten sonra aşağıda oluşan bilgileri twiki.conf isimli bir dosyaya koyun, ve bu dosyayı da /etc/httpd/conf.d altına koyun. Apache'nin konfigürasyon dosyasında bulunan Include conf.d/*.conf satırı, bu conf dosyasının otomatik olarak okunmasını sağlayacak.

• “chmod 644 twiki.conf” ve “ chown root:root twiki.conf” komutlarını conf.d klasörü altında çalıştırmamız gerekiyor.

• Apache konfigürasyonunu bitirdikten sonra ilk ayarları yapacak olan kullanıcıyı yaratma kısmına geldik. “htpasswd -c /var/www/twiki/data/.htpasswd oguz” komutu ilk kullanıcımızı yaratıyor. Eğer “-c” parametresini kullanmazsak, yeni kullanıcıyı bu listenin sonuna ekliyor. Aksi takdirde, bu dosyayı sıfırlıyor. “-c” yerine “-D” kullanırsak kullanıcıyı siliyor. Twiki kurulumu bittikten sonra yaratılan her kullanıcı bu dosya içerisine eklenecek.

• /var/www/twiki/bin klasöründeki LocalLib.cfg.txt dosyasını LocalLib.cfg'ye çevirmek ve ardından içerisinde twikiLibPath parametresini doğru bir şekilde düzeltmek gerekiyor...

• SDosyalar üzerinde bazı yetkilerin verilmesi gerekiyor. Bu yetkileri SettingFileAccessRightsLinuxUnix linkinde bulabilirsiniz.

• Son işimiz Apache'yi ayağa kaldırmak olacak. “service httpd start” yazıyoruz ve ardından http:///twiki/bin/configure yazarak konfigürasyona geçiyoruz.

• Bundan sonraki ayarları Run Configure For The First Time linkindeki bilgiler ışığında yapabilirsiniz

• Bunun dışında tam kurulum dokümanını TwikiOnRedHat linkinde bulabilirsiniz.

Umarım memnun kalırsınız...

Dokümantasyon ve Twiki – I (Dokümantasyon)

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.

Sun ve wiki

Wiki yazmak bilginin paylaşılması ve devamlılığı açısından oldukça önemlidir. Etrafınızda yüzlerce wiki engine var. Bunlardan en bilinenleri Twiki, en.wikipedia.org 'un kullandığı MediaWiki ve Confluence . Ama bizi ilgilendiren Sun'ın wiki sayfası. Sun'ın wiki sayfası Confluence ile yapıldı. Şimdilik içeriği yavaş yavaş doluyor. Ama Sun'dan bazı arkadaşlar Sun'da dokümantasyonun hızlı bir tarihçesini anlatan güzel bir video hazırlamışlar. "Publishing @ Sun" bol bol göreceğiniz bir slogan. Keyifle izlenecek bir gösteri. Aşağıdaki filmi izlemekte sıkıntı yaşarsanız, bu linkten izleyebilirsiniz.