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

Teknik dokümantasyon, yazıldığı gün altın değer taşır. Bir ay sonra ise çoğu zaman sadece bir "biz bunu bir zamanlar böyle yapıyorduk" artefaktına dönüşmüştür. Bu döngüyü kırmak mümkün — ama bunun için birkaç alışkanlığı kasıtlı olarak benimsemek gerekiyor.

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

Kodlar değişir, sistemler evrilir; ama dokümantasyon çoğunlukla olduğu yerde durur. Bunun birkaç temel sebebi var:

• Sahiplik belirsizliği: Kim yazarsa yazar, kimse güncelleme sorumluluğunu üstlenmez.
• Dokümantasyon, geliştirmenin dışında tutulur: Bir özellik tamamlandığında yapılacaklar listesinin en altına sıkışır.
• Araç karmaşası: Confluence, Notion, README, wiki, Word dosyası… Bilgi her yere dağılınca hiçbir yerde yaşamaz.

"Docs as Code" Yaklaşımı

Sürdürülebilir dokümantasyonun en sağlam temeli, onu kod gibi yönetmektir. Bu ne anlama gelir?

• Dokümantasyonu kaynak kod deposunda (Git) tutmak
• Pull request süreciyle review etmek
• CI/CD pipeline'ına lint ve bağlantı kontrolü eklemek
• Her değişiklik kaydının tarihini ve yazarını görünür kılmak

Bu yaklaşım, dokümantasyonu geliştirme sürecinin doğal bir parçası hâline getirir. Kod merge edilmeden önce ilgili doküman güncellenmediyse pipeline bunu hatırlatabilir.

Sahiplik Modeli Kurun

Her dokümanın bir sahibi olmalı. Bu "tek kişi her şeyi bilir" anlamına gelmiyor; aksine şu anlama geliyor: Bu sayfanın güncel kalmasından kim sorumlu?

Küçük ekiplerde bu rotasyonla çözülebilir. Büyük ekiplerde ise her servis ya da domain'in bir "documentation steward"ı olabilir. Önemli olan hesap verebilirliğin net olmasıdır.

Minimal Ama Doğru Yazın

Kapsamlı dokümantasyon yazmak cazip gelir. Ama 40 sayfalık bir döküman, 6 ay sonra %80 oranında eskimiş olacaksa hiç yazılmamış bir dökümandan daha tehlikelidir — çünkü insanlara yanlış bilgi verir.

Bunun yerine şunları tercih edin:

• Kısa ve odaklı sayfalar: Tek bir kavramı ya da akışı anlatan, genişletilmesi kolay içerikler.
• "Son güncelleme" tarihi zorunluluğu: Tarihi olmayan bir doküman, güvenilmez bir dokümandır.
• Evergreen içerik ile anlık notları ayırın: "Bu sistem nasıl çalışır?" ile "Bu sprint'te ne yaptık?" farklı yerlere ait.

Review Ritüelleri

Dokümantasyonu yaşatmak için düzenli ritüeller şart:

• Üç ayda bir dokümantasyon sprintiː Sadece güncelleme, silme ve reorganizasyon için ayrılmış zaman.
• Onboarding geri bildirimi: Yeni katılan bir ekip üyesinin dokümantasyonu takip ederek ilk işini yapması, hangi boşlukların olduğunu anında ortaya çıkarır.
• "Bu hâlâ doğru mu?" sorusu: Her incident retrospektifinde ya da büyük teknik değişiklikte, ilgili dokümanlara mutlaka bakın.

Araç Seçiminde Sadelik

Araç tartışmaları enerjinizi tüketebilir. Şunu söyleyeyim: En iyi araç, ekibinizin gerçekten kullandığı araçtır. Bununla birlikte birkaç kriter yol gösterici olabilir:

• Arama kalitesi yüksek olmalı
• Versiyonlama desteklenmeli
• Erişim engeli düşük olmalı (kurulum, login, format karmaşası olmadan açılabilmeli)

Son Söz

Teknik dokümantasyon bir proje değil, bir alışkanlıktır. Tek seferlik bir "hepsini yazalım" hamlesinden çok, her teknik kararın yanına küçük bir not düşme disiplininden doğar. Sistemin doğasını değil, insanların davranışlarını değiştirmeye odaklanın — geri kalanı zamanla yerine oturur.