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

Bir sistemi aylar önce kuruyorsunuz, her şeyi kafanızda tutuyorsunuz. Sonra biri soruyor: "Bu servis neden böyle çalışıyor?" Cevabı biliyorsunuz ama yazmadınız. Altı ay sonra siz de unutuyorsunuz. İşte teknik dokümantasyonun en klasik trajedisi bu.

Dokümantasyon yazmak zor değil aslında. Ama yazdığınızı güncel tutmak — işte asıl mesele bu.

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

Kod değişir, sistem evrilir; ama doküman olduğu yerde durur. Bunun birkaç temel nedeni var:

• Dokümantasyon, geliştirme sürecinden ayrı tutulur. "Önce bitirelim, sonra yazarız" kültürü her ekipte vardır. Ama "sonra" çoğu zaman gelmez.
• Sahiplik belirsizdir. Kim günceller? Yazan mı, kullanan mı, ekip lideri mi? Herkesin sorumluluğu kimsenin sorumluluğuna dönüşür.
• Güncelleme maliyeti görünmezdir. Bir özelliği değiştirmek PR açmayı, test yazmayı gerektirir — ama dokümanı güncellemek "ayrı bir iş" gibi hissettirdiğinden ertelenir.

Sürdürülebilirliğin Temeli: Docs as Code

Benim için en işe yarayan yaklaşım "docs as code" felsefesi. Dokümantasyonu, kodun yanında — aynı repoda, aynı PR sürecinde — yaşatmak. Bu sayede:

• Kod değiştiğinde doküman da gözden geçirilmek zorunda kalır.
• Review sürecinde "bu değişikliği dokümana yansıttın mı?" sorusu doğal olarak sorulur.
• Versiyon geçmişi şeffaftır; kimin ne zaman ne değiştirdiğini görebilirsiniz.

Markdown tabanlı araçlar (MkDocs, Docusaurus, VitePress) bu yaklaşım için oldukça olgun bir ekosisteme sahip artık.

Pratik Alışkanlıklar

Felsefeyi bir kenara bırakıp günlük rutinlere bakacak olursak:

1. "Definition of Done"a ekleyin. Bir görev, dokümantasyonu güncellenmedikçe bitmemiş sayılsın. Bu basit kural, dokümantasyonu isteğe bağlı olmaktan çıkarır. 2. Kısa ve odaklı yazın. Kapsamlı bir wiki sayfası yerine, tek bir soruyu yanıtlayan küçük dokümanlar daha uzun yaşar. "Bu servis ne iş yapar?" ve "Bu servis nasıl deploy edilir?" ayrı sayfalar olsun. 3. "Neden"i yazın, "ne"yi değil. Kodu okuyarak "ne" yaptığını anlayabiliriz. Ama o kararın neden alındığını ancak doküman söyler. Architecture Decision Record (ADR) formatı bunun için biçilmiş kaftan. 4. Düzenli "doküman turu" yapın. Her sprint sonunda ya da aylık olarak ekipçe eski dokümanları gözden geçirin. Tarihli veya yanlış içerikleri işaretleyin, silin ya da güncelleyin. 5. Okuyucuyu tanıyın. "DevOps ekibi için mi yazıyorum, yeni başlayan bir geliştirici için mi?" sorusunu cevaplamadan yazılan doküman genellikle hiçbirine hitap etmez.

Araç Seçimi Kültürü Yenmez

Son olarak şunu söylemek isterim: Confluence, Notion, Obsidian, GitHub Wiki — hangisini seçerseniz seçin, araç problemi çözmez. Kültür olmadan hiçbir araç çalışmaz. Ekip olarak "dokümantasyon önemlidir" kararını vermezseniz, en güzel wiki sistemi de zamanla örümcek ağına döner.

Sürdürülebilir dokümantasyon bir sprint işi değil, bir alışkanlık meselesi. Ve alışkanlıklar ancak küçük, tutarlı adımlarla inşa edilir.

---

Bu yazı hakkında düşünceleriniz varya da eklemek istediğiniz bir pratik varsa, yorumlarda buluşalım.