9 Mayıs 2013 Perşembe

Agile Belgeleme: Bir Kabusun Sonu

İnkar etsek de etmesek de onunla ciddi bir derdimiz var. Birbirimize bir türlü alışamadık, ısınamadık. Ne onunla olabiliyoruz, ne de onsuz. Ondan vazgeçemiyoruz. Şu an olmasa bile ona bir gün mutlak ihtiyacımız olduğunu düşüncesi aklımızdan hiçbir an çıkmıyor. Ancak onunla da yapamıyoruz. Onunla ilgilendiğimiz zamandar bize adeta zulüm, ızdırap oluyor. Saatlerle, günlerle ifade edilen bir emek ve bu emeğin karşılığı çoğu zaman bir hiç oluyor. Üstüne üstük sürekli ilgi ve bakım istiyor, lakin buna vakit yok. Onunla ilgilenmek listemizde hep en sonlarda kalıyor. Bakımını yapmak zorundayız ve bakımını yapmadığınız her an ondan biraz daha kopuyoruz. Bir de bakmışsınız ki tamamı eski ve işe yaramaz, hem de ona en ihtiyacınız olduğu bir anda..

Dökmantasyondan bahsediyorum. Ona türlü türlü nedenlerle ihtiyacımız var.

  • Müşterilerinize uygulamamız "nasıl çalışır"ı anlatmak için
  • Müşteriden uzun uğraşlar sonrasında topladığınız yazılım gereksinimlerini sıralamak için
  • Gereksinimlerin detaylarını örneklerle açıklamak için
  • Tasarımlarımızı kaydetmek ve takımla paylaşmak için
  • Uygulamalardaki akışları ve işlevleri anlatmak, detaylarını  paylaşmak için
  • Takıma yeni katılabilecek kişilere uygulamayı daha rahat anlatabilmek için
  • Aynı sorunlar tekrar tekrar yaşanmaması için sorunları "nasıl çözdüğümüzü" kaydetmek için
  • Teknik bilgi ve deneyimlerimizi paylaşmak için
  • Yazılım (teknolojileri ve teknikleri ile birlikte) en doğru şekilde nasıl geliştiriliri not düşmek için
  • Test sonuçlarımızı kaydetmek için
  • Yapılacak işleri listelemek ve kalan işleri net görebilmek için
  • Çıkan hataları listelemek ve bazen de müşteri ile bunları paylaşmak için
  • Çıktığınız sürümde nelerin değiştiğini başkaları ile paylaşmak için
  • Toplantı notlarını paylaşmak için

ve daha birçok neden için belgelemeye ihtiyaç duyuyoruz. Çoğu kez "wiki" dediğimiz çevrimiçi araçlar kullanıyoruz . Çok anlamlı amaçlar için yazmak, başkaları da okusun ve faydalanılsın istiyoruz. Yazdıklarımızı paylaşıyoruz ki başkaları okusun ve...

  • Problemlerini çözecek bilgilere ulaşsın
  • Aklındakilerin tam anlamıyla karşı tarafa aktarıldığını görmüş olsun
  • Bir sorunu olduğunda çözümünü bulmuş olsun
  • Yazılımı nasıl geliştirmesi gerektiğini tasarımları ile görsün
  • Teknik bilgi ve becerisini geliştirmiş olsun
  • Hataları ve olası çıkabilecek problemleri bilsin
  • Yeni geliştirmelerden haberdar olsun
  • Son durumu net görsün
  • Takıma bilgi açısından daha hızlı adapte olsun

Gerçeklerle yüzleşelim

Ancak gerçekler hiç de öyle göründüğü gibi değil. Kabul edelim, genele vurduğunuzda görüyoruz ki hiçbir yazılımcı dökümantasyon yapmak istemiyor. Kendimiz dahil. Onca keyifli iş dururken belgelemek bize çok zor geliyor. İş listesinde hep en sona bırakıyoruz ve çoğunlukla da büyük bir keyifle "zaten zamanımız yoktu" bahanesiyle yapmamayı tercih ediyoruz.

Yaptık diyelim, yine genele vurarak konuşursak, yazdığımız belgeleri ya birkaç kişi bir kez okusun diye yazıyoruz, yada zaten kimse okumuyor. Bu büyük bir hayal kırıklığı aslında. Tek amacı paylaşılmak olan ve özenle hazırlanan belgelerin hiç bir işe yaramadığını görmek çok üzücü malesef.

Malesef zamanın akışı dökümantasyonları doğrudan etkiliyor. Bugün yazdığınız belge yarın geçersiz ya da eski oluyor. Belgeleri güncel tutamıyoruz, ve bir süre sonra elimizde bir çuval dolusu işe yaramaz bilgi kalıyor.

Çoğu kez de belgemizi gereksiz tonlarca bilgi ile dolduruyoruz. Sayfa tasarımını, bilginin veriliş şeklini hatalı yapıyoruz. Okunması güç, anlaşılması güç belgeler hazırlıyoruz.  

Peki biz nerde hata yapıyoruz? Daha verimli bir belgeleme sistemi nasıl oluşturabiliriz? 

Agile Belgeleme (Dökümantasyon)

Agile Belgeleme (Dökümantasyon) tam da bu noktada karşımıza çıkıyor. Çok basit bir şekilde, vermek istediği mesaj şu üç kelime ile açıklanabilir: "Yeteri kadar dökümantasyon". Önerdiği en beğenilen pratikler (best practices) şöyle sıralanabilir.
  • Hazırlayacağınız yazının hedef kitlesini iyi belirleyin. Müşteri, müdür, iş bölümü yada yazılımcı olabilir.  Okuyucu kitlesini belirlemeniz belgelerken ne oranda detaya ineceğinizi belirlemenize yardımcı olur. Yeteri kadar bilgi vermek en öncelikli hedefimiz olmalı.
  • Paragraflar dolusu yazı yazmak yerine kısa cümleler ve bolca grafik ve tablo kullanın. Yazılımın detaylarını cümlelere dökmek yerine akış diyagramları ve tablolar çok daha faydalı olacaktır.
  • Okuyucunuza "eksik bilgi var mı" sorusu yanında "senin için daha okunaklı nasıl yazabilirdim" sorusunu da sorun. Eminim "şu bilgileri şu biçimde verseydin daha anlaşılır olurdu" ya da "şu bölümlere gerek yoktu" geribildirimlerini duyacakınız.
  • Birçok belgeniz eskiyecek ve atıl duruma düşecek. Bundan kaçış yok. Eski ve kullanılmayan belgelerinizi ya güncelleyin, ya tamamen silin, ya da arşivleyin. Sakın güncel belgelerinizle aynı mekanda bırakmayın.
  • Wikinizde mutlaka güncel tutmakla sorumlu ve zorunda olduğunuz bir bölüm bulunsun. Burada sadece ve sadece güncel belgeleri tutun. Her fırsatta da buradaki belgeleri güncelleyin. Böylelikle güncelliğinden emin olduğunuz belgelerin varlığı ile huzur duyacaksınız.
  • Belgelere içeriği tam anlatan isimler verin. Gazete başlıkları gibi isimler bulunmayı zorlaştırır.
  • Yeni belgeler oluşturmaktan korkmayın. Belge çöplüğü oluşamaması için belgenizi mutlaka doğru kategori altına yerleştirin.
  • Grafik çizdiyseniz ve sayfanıza yerleştirdiyseniz, mutlaka kaynak dosyasını da belgeye ataçlayın. Böylelikle günler sonra belgeyi güncellemek gerektiğinde aynı grafik üzerinde değişiklik yapabilirsiniz.
  • Gözünüze çarpan eskimiş belgeleri eğer güncelleyebiliyorsanız güncelleyin. Yoksa boşuna uğraşmayın, daha önce dediğim gibi silin/arşivleyin gitsin.
  • Yazılımcılar da dökümantasyon yapar. Özellikle tasarımı, işlevleri ve akışları anlatan grafiklerle, test sonuçlarını ve verileri içeren tablolarla. Belgelemeden kaçmayın, bilakis özen gösterin. Siz bile bundan 2 hafta sonra neyin nasıl çalıştığını hatırlamak için kendinizi hazırladığınız belgelere bakarken bulacaksınız.
Dökümantasyon kabusunuz olmasın. Akıllıca hazırlanmış bir belgenin kıymetinin binlerce satır koda değer olduğunu asla unutmayın. Hazırladığınız belgeler için "çok faydalandım" geribildirimi almanız dileğimdir:)

0 yorum:

Yorum Gönder

Template developed by Confluent Forms LLC; more resources at BlogXpertise