Dokumantasyon

Farkında mısınız bilmiyorum ama; çok uzun zamandır buralarda değildim. Esasında buralarda olmama rağmen, ne buraya ayıracak zaman ne de burayı düşünecek gücüm vardı…

Yaklaşık 3 ay önce hayatımı itina ile dağıtıp (evet en ufak parçasına kadar) itina ile topladım (bilenler biliyor, bilmeyenler de pek sormazlarsa sevinirim ). Daha sonra master’ın ikinci dönemi başladı ama; hayatımı dağıtmadan evvel ve hatta hayatımı topladıktan sonra bile başımda kalan bir dert var ki, bu okuduğunuz yazıya ilham kaynağı oldu.

Bilmediğim bir zaman evvel, bir toplantıda benden kurum içerisine bir belge sunucusu kurmam istendi. Aday program olarak da CERN’in geliştirdiği CDS-Invenio gösterildi. Ben de her işini seven çalışan gibi koşa koşa siteye gittim, programı indirdim, derledim (web sitesi python / HTML ile beraber geliştirildiği için, siteyi kurmadan evvel derlemeniz gerekmekte) ve 15 dakika içerisinde masaüstü sistemime kurdum. Hayatımın en keyifli 15 dakikası olduğunu rahatlıkla söyleyebilirim çünkü hem ayarlar ve kurulum pratikti, hem de kurma talimatları debian için verilmişti. Biraz “deb” elendikten, biraz “configure” yaptıktan ve “make -j2″ ile orta ateşte az pişirdikten sonra, istediğim ayarlara (isim, posta adresleri, başlıklar, vs) sahip bir döküman sunucum olmuştu. Sevinçliydim çünkü; tahmin ettiğimden kolay olmuştu ve en önemlisi olmuş görünüyordu derken, siteyi istediğim gibi uyarlamak için çalışmaya başlayınca, bunun pek de öyle olmadığını anladım.

Siteyi kendi makineme kurduğum için, “istersen demo site de kurayım, kurcalarsın bak” seçeneğini de seçtim. İyi ki seçmiş olduğumu anlamam için pek kısa bir süre geçmiş olması yetti zaten. Siteyi kurduktan bir süre sonra, yanıma bir tane sunucu alıp önce üzerine debian, sonra da CDS-Invenio kurdum. Orada da bir iki pürüz çıkmasına rağmen her şey yolunda gitti ve bir günde sunucuyu ayağa kaldırdım. Savaş daha yeni başlıyordu da benim haberim yoktu.

Siteyi kurduktan sonra yönetici sayfasına girince şok geçirdim. Çünkü gördüğüm kadarı ile belge göndermekten indeksleme işlemine kadar her şey birbirinden bağımsızdı ve daha da kötüsü, döküman gönderme formu ve veri işleme filtrelerine kadar her şeyi benim”yazmam” gerekiyordu bu da en basitinden bütün sistemi okuyup anlamam gerektiği anlamına geliyordu. Olsun, her bölümde bir de “guide” linki vardı.

Siteyi inceledim ve planımı yaptım. Önce döküman göndermeyi becerecek, sonra bunları kataloglayacak, en son da indeksleyecektim. Sevinçle döküman gönderme kısmının kullanıcı kitabı linkine tıkladım ve sayfa geldi ama tepede bir uyarı ile “Ekteki sayfa eski belge gönderme yönetim paneli’nin belgeleridir. Yeni yönetim paneli’nin sadec görünümü değiştiği için, bu belgeyi kaynak olarak kullanmaya devam edebilirsiniz. Veri işleme bölümünde ise işler daha kötüydü. Veri işleme dilinin en önemli yerlerinin analtıldığı bölümde sadece “FIXME: Add guide about XML mode” yazıyordu. En azından onun yazıyor olmasına sevinmem gerektiğini katalog bölümünün dökümantasyonun tamamlanmamış olduğunu farkedince anladım ancak…

Peki yardımcı ve açıklayıcı belgeler olmadığı ben bu siteyi kuramadım mı? Hayır. Site şu anda kurulu ve gayet güzel hizmet veriyor ama; dökümanları tam olsaydı benim bu siteyi kurmam en fazla 3 haftamı alacaktı. Bu senaryoda ise bütün dökümanları okumam, sistemi anlamam, bir yerlerden MARC21 spesifikasyonlarını okuyup anlam verebilir hale gelmem, daha sonra kendi bilgisayarımda kurmuş olduğum demo siteyi reverse-engineer ile çözmem (sitede bazı yerlerde basit de olsa programlama yapmanız gerekiyor ve açıklanan hiç bir şey yok, eğlenceyi siz düşünün) sonra onları taşımam, uyarlamam, ince ayarlarını yapmam ve bir çok arka servisi kurcalayarak anlamam ve ayarlamam gerekti. Yani sisteme aylarımı verdim, üzerine bir de stres oldum yetiştirmek için.

Siz siz olun, yazdığınız her şey için basit de olsa tam ve açıklayıcı bir dökümantasyon yazın ya da en azından sistemin adım adım nasıl çalıştığını anlatın ki kullananlar en azından ne yapmaları gerektiğini bilsinler.