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

Şunu itiraf edelim: Çoğu ekipte teknik dokümantasyon, projenin en ihmal edilen parçasıdır. Kod commit'lenir, özellikler çıkar, sistem büyür — ama dökümantasyon iki yıl önceki mimariye bakar, kimse güncellemez. Sonunda kimse güvenmez, kimse okumaz, kimse yazmaz. Kısır döngü başlar.

Bu yazıda dokümantasyonu "bir kere yazılıp unutulan bir görev" olmaktan çıkarıp gerçekten yaşayan, güvenilen bir sistem hâline getirmenin yollarına bakacağız.

Neden Sürdürülemez Hâle Gelir?

Sorun çoğunlukla motivasyon ya da bilgi eksikliği değil, yapısal bir tasarım hatasıdır. Dökümantasyon kod tabanından kopuk yaşıyorsa eskir. Yazmak zorunda olan kişi belli değilse kimse yazmaz. Gözden geçirme süreci yoksa yanlış bilgi yıllarca orada durur.

Birkaç yaygın ölüm nedeni:

• Dökümantasyon ayrı bir araçta, kod ile senkronize değil
• "Sonra yazarız" kültürü — ki o "sonra" hiç gelmez
• Tek bir kişinin sorumluluğunda olması (o kişi gittiğinde her şey gider)
• Yazılmış ama okunmadığı için güncelleme motivasyonu sıfır

Docs as Code: Belgeyi Koda Yaklaştırın

En etkili yaklaşımlardan biri "Docs as Code" felsefesidir. Dökümantasyonu, tıpkı kod gibi versiyon kontrolünde tutarsınız (Git), pull request sürecine dahil edersiniz ve CI/CD pipeline'ınıza entegre edersiniz.

Pratik adımlar:

• Markdown veya AsciiDoc kullanın, Word/Confluence bağımlılığını azaltın
• Dokümanları ilgili servis ya da modülün yanına koyun (/docs klasörü)
• Her PR'a "Bu değişiklik dökümantasyon gerektiriyor mu?" sorusunu ekleyin
• Eski veya eksik dökümanlara otomatik uyarı veren lint kuralları yazın

Bu yaklaşım mükemmel değil, ama dökümantasyonu geliştirici iş akışının içine taşır. "Ayrı bir iş" olmaktan çıkar.

Sahiplik ve Sorumluluk

Kolektif sahiplik güzel bir fikir ama pratikte "herkesin işi kimsenin işi değildir." Her kritik dökümantasyon parçasının bir sahibi olmalı. Bu kişi içeriği yazan değil, güncel tutulmasından sorumlu olan kişidir.

Bunun için:

• Her dokümanın başına owner: ve last-reviewed: meta verisi ekleyin
• Üç ayda bir otomatik hatırlatıcı gönderin: "Bu doküman hâlâ geçerli mi?"
• Onboarding süreçlerinde yeni ekip üyelerine dökümantasyon okutun — hatalar hemen ortaya çıkar

Yazma Bariyerini Düşürün

İnsanlar dökümantasyon yazmaktan kaçınır çünkü yüksek kaliteli, kapsamlı bir şey yazmaları gerektiğini düşünürler. Bu beklentiyi kırın.

• Kısa "decision log" girişleri (neden bu teknolojiyi seçtik, 5 cümle yeter)
• README'lere küçük ama doğru notlar
• Ekip içi Slack açıklamalarını yapılandırılmış hâle getirme alışkanlığı

Mükemmel ama güncel olmayan bir doküman, eksik ama doğru olan birinden çok daha tehlikelidir.

Dökümantasyonu Ölçün

Neyin işe yaradığını anlamak için basit metrikler kullanın:

• Son 6 ayda güncellenmemiş doküman sayısı
• Onboarding sırasında sorulan tekrarlayan sorular (bunlar eksik dokümanın işareti)
• Dökümantasyon kaynaklı destek taleplerinin oranı

Bu rakamlar dökümantasyona yatırım yapmanın somut gerekçesini oluşturur.

Sonuç

Sürdürülebilir dökümantasyon bir yazma meselesi değil, bir sistem tasarımı meselesidir. Doğru araçları, net sahiplikleri ve yazma bariyerini düşüren bir kültürü bir araya getirdiğinizde, dökümantasyon "yapılması gereken sıkıcı iş" olmaktan çıkıp ekibin gerçekten güvendiği bir altyapıya dönüşür.

Ve o noktaya geldiğinizde, onboarding hızlanır, hatalar azalır, herkes biraz daha az stres yaşar. Bence buna değer.