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

Yazılım geliştirme dünyasında en çok ihmal edilen şey nedir diye sorsanız, cevap büyük ihtimalle aynı olur: dokümantasyon. Herkes onun önemli olduğunu bilir, ama kimse onu güncel tutmayı sevmez. Sonuç? Altı ay sonra kimsenin güvenmediği, yarısı yanlış, yarısı eksik bir belge yığını.

Bu yazıda, teknik dokümantasyonu "bir kez yazılıp unutulan" bir şey olmaktan çıkarıp, gerçekten yaşayan ve değer üreten bir sisteme nasıl dönüştürebileceğinizi konuşacağız.

Neden Belgeler Bu Kadar Hızlı Eskir?

Sorunun kökü genellikle şuradadır: dokümantasyon, geliştirme sürecinin bir yan ürünü olarak görülür, birincil çıktısı olarak değil. Bir özellik eklenir, kod yazılır, PR merge edilir — ama belge ya hiç yazılmaz ya da aceleyle bir yere yapıştırılır.

Bunun yanı sıra şu faktörler de işin içine girer:

• Sahiplik belirsizliği: "Bu belgeyi kim güncelleyecek?" sorusunun net cevabı yoktur.
• Araç karmaşası: Confluence'ta mı, Notion'da mı, README'de mi, yoksa o eski Word dosyasında mı?
• Güncelleme maliyeti: Belgeyi güncellemek, kodu değiştirmek kadar "görünür" bir iş değildir.

Docs-as-Code: Belgeleri Kodla Birlikte Yaşatmak

En etkili yaklaşımlardan biri, dokümantasyonu kod tabanıyla aynı repository içinde tutmaktır. Bu yaklaşımın adı Docs-as-Code.

Temel fikir basit: Markdown formatında yazılmış belgeler, kaynak kodla birlikte versiyonlanır. PR açıldığında belgeler de review edilir, kod değiştiğinde ilgili belge de değişmek zorundadır.

Pratik faydaları şunlardır:

• Geri izlenebilirlik: git blame ile kimin ne zaman ne yazdığını görebilirsiniz.
• Review kültürü: Kod review'ında belge eksikliği de yakalanır.
• CI/CD entegrasyonu: Otomatik testler bozuk linkleri, eksik parametreleri tespit edebilir.

Küçük Ama Etkili Alışkanlıklar

Büyük süreç değişikliklerine gerek olmadan da önemli adımlar atılabilir:

1. Her PR'a bir belge kuralı koyun. "Bu değişiklik mevcut bir belgeyi etkiliyor mu?" sorusu PR şablonuna eklenebilir. 2. Belge sahibi atayın. Her kritik belgenin bir sorumlusu olsun. Bu kişi rotasyonla değişebilir, ama belirsiz olmamalı. 3. "Son Doğrulama Tarihi" ekleyin. Belgenin başına son gözden geçirildiği tarihi yazın. Eski tarih, okuyucuya otomatik uyarı verir. 4. Belgeyi kısa tutun. Uzun belgeler okunmaz, okunmayan belgeler güncellenmez. Tek bir konuya odaklanın.

Otomasyondan Yararlanın

İnsan disiplinine tamamen güvenmek yerine, süreci otomatikleştirin:

• Link checker araçları (örneğin lychee veya markdown-link-check) bozuk referansları otomatik bulur.
• OpenAPI / AsyncAPI gibi şema tabanlı araçlar, API belgelerini doğrudan kod tanımlarından üretir — böylece belge ile kod arasındaki uçurum kapanır.
• Changelog otomasyonu (Conventional Commits + release-please gibi araçlar) değişiklik geçmişini elle yazmak zorunda bırakmaz.

Kültür Meselesi

Sonuçta teknik olmayan bir gerçekle yüzleşmek gerekiyor: Sürdürülebilir dokümantasyon bir kültür meselesidir.

Araçlar ve süreçler yardımcı olur, ama takım olarak "iyi belge yazmak profesyonelliğin bir parçasıdır" anlayışı benimsenmeden hiçbir sistem işe yaramaz. Bunu bir yük olarak değil, bir saygı eylemi olarak görmek gerekiyor — gelecekteki ekip arkadaşlarınıza, hatta altı ay sonraki kendinize karşı.

Dokümantasyonu mükemmel yapmaya çalışmayın. Önce var olmasını, sonra güncel kalmasını, sonra iyi olmasını sağlayın. Bu sıralama önemli.