Teknik Dokümantasyonu Sürdürülebilir Kılmak

Çoğu ekip, bir sistem kurulurken dokümantasyona özen gösterir. Ama aradan altı ay geçince o belgeler gerçeklikten kopmuş, kimsenin güncellemediği bir "tarihî arşiv"e dönüşür. Bu yazıda teknik dokümantasyonu neden kaybettiğimizi ve onu gerçekten yaşayan bir yapıya nasıl dönüştürebileceğimizi konuşacağız.

Dokümantasyon Neden "Çürür"?

Belgelerin eskimesinin ardında genellikle şu üç sebep yatar:

• Sahiplik belirsizliği: Kimse "bu dokümanın sahibi benim" demez, dolayısıyla kimse güncellemez.
• Yazma ve çalıştırma ayrımı: Kod değişir, PR açılır, merge edilir; ama ilgili dokümanı güncellemek isteğe bağlı kalır.
• Araç sürtüşmesi: Ekip Slack'te, kod GitHub'da, doküman ise bambaşka bir yerde. Bağlamı değiştirme maliyeti yüksek olunca yazmaktan vazgeçilir.

Sonuç: Ekip üyeleri dokümana güvenmemeye başlar, sözlü aktarıma ya da "kod okumak" zorunda kalmaya alışır. Bu döngü kırılmadan sürdürülebilirlik mümkün değil.

Docs-as-Code: Belgeyi Kodun Yanına Taşımak

En güçlü yaklaşımlardan biri, dokümantasyonu kodla aynı depoda tutmak ve aynı iş akışına dahil etmektir. Markdown veya AsciiDoc dosyaları, özellik dallarıyla birlikte güncellenir; PR açılırken "docs güncellendi mi?" sorusu bir checklist maddesi haline gelir.

Bu yaklaşımın somut faydaları:

• Değişiklik geçmişi (git blame) sayesinde bir bilginin ne zaman, neden güncellendiğini görmek mümkün olur.
• CI/CD pipeline'ına lint veya kırık bağlantı kontrolü eklenebilir.
• Geliştiriciler zaten bildiği araçları (editor, PR süreci) kullanır; öğrenme eğrisi sıfıra yaklaşır.

Sahiplik Modelini Netleştirmek

Doküman sahipliği için CODEOWNERS benzeri bir yaklaşım benimseyebilirsiniz. Her dizin ya da konu alanı için bir sorumlu belirlenir. Bu kişi içeriği tek başına yazmak zorunda değildir; ama güncel kalmasından sorumludur.

Bunun yanı sıra şu iki kuralı ekibinizle konuşmanızı öneririm:

1. "Bunu öğrenmek için 15 dakikadan fazla harcadıysan, çözümü belgele." Bugün seni durduran şey yarın bir başkasını da durduracak. 2. Review sırasında "Bu değişiklik bir dokümanı etkiliyor mu?" sorusunu sormayı alışkanlık haline getir. Kod incelemesi dokümantasyon incelemesini de kapsamalı.

Periyodik "Doküman Bakımı"

Sürdürülebilirlik yalnızca yazım anındaki alışkanlıklarla değil, düzenli bakımla sağlanır. Pek çok ekipte işe yarayan bir yöntem: her sprint'in sonuna ya da her ayın ilk Cuma'sına kısa bir docs grooming seansı eklemek.

Bu seanslarda sorulacak sorular basit olabilir:

• Hangi sayfayı son üç ayda kimse güncellemedi?
• Hangi başlık artık kullanılmayan bir mimariyi anlatıyor?
• Hangi soruyu yeni katılan biri bize tekrar tekrar sordu?

Cevaplar, öncelik listesini neredeyse otomatik olarak çıkarır.

Ölçüt: Yeni Gelen Biri Ne Kadar Sürede Bağımsız Olabiliyor?

Dokümantasyonun kalitesini ölçmenin en dürüst yolu, ekibe yeni katılan birine bakmaktır. İlk haftasında kaç kez bir insana soru sormak zorunda kaldı? Eğer cevap "çok sık" ise, dokümantasyonunuzda boşluklar var demektir.

Bu metriği soyut bırakmamak için yeni katılanlardan "onboarding sırasında bulunmayan ama işini kolaylaştıracak bir belge yaz" isteyebilirsiniz. Hem öğrenirler, hem de gerçek bir boşluğu kapatırlar.

---

Teknik dokümantasyon bir "nice to have" değil, ekibin uzun vadeli hızını belirleyen bir altyapı unsurudur. Onu yaşatmak için büyük bir proje başlatmak yerine küçük alışkanlıkları sisteme gömmek çok daha kalıcı sonuç verir. Belki bugün başlamak için yapılacak tek şey, ekibin bir sonraki PR şablonuna tek bir soru eklemektir: "Belgelenecek bir şey var mı?"