Teknik Dokümantasyon Dağınıklığı: Kararları Node'larda Tut

Teknik Dokümantasyon Dağınıklığı: Kararları Node'larda Tut

Altı ay önce PostgreSQL'den MongoDB'ye geçmeme kararı alındı. Neden? Kim karar verdi? Hangi alternatifler değerlendirildi? Redis neden elendi?

Bu soruların cevabı bir yerlerde var. Belki Confluence'ta yarım kalmış bir sayfada, belki Notion'da kimsenin güncellemediği bir dokümanda, belki o toplantının Slack thread'inde. Yeni katılan geliştirici bu soruyu soruyor, kimse tam cevap veremiyor. "Hep böyle yapmışız" deniyor.

Teknik kararların kaybolması ürün kalitesini etkiliyor. Aynı tartışmalar tekrar açılıyor, reddedilen çözümler yeniden deneniyor, bağlam olmadan yapılan değişiklikler önceki kararları farkında olmadan bozuyor.

Teknik Notlar Neden Dağılıyor?

Teknik dokümantasyon dağılmasının kendine özgü bir dinamiği var. İyi niyetle başlıyor ama sürdürülemiyor.

Araç çokluğu standart öldürüyor. Confluence var, Notion var, GitHub wiki var, README var. Her geliştirici farklı bir yere yazıyor. Standart olmadığında arama yapılacak tek bir yer yok. "Nerede yazmıştım?" sorusu "yazmamıştım" cevabına dönüşüyor.

Karar anında yazılmıyor. "Sonra belgelerim" kararı genellikle hiç belgelenmemek anlamına geliyor. Toplantıdan çıkıldığında bağlam hâlâ taze, iki gün sonra detaylar uçmuş. İki hafta sonra neden o kararın alındığı hatırlanmıyor.

Format yok, derinlik yok. "Redis'i seçtik" bir karar kaydı değil. Hangi alternatifleri değerlendirdik, neden Redis'i seçtik, hangi kısıtlar bizi buna yöneltti, trade-off'lar nelerdi — bunlar yazılmadan karar yarım kalıyor.

Bağlantı yok. Karar bir yerde duruyor, ilgili görev başka bir yerde. İkisi arasında köprü olmadığında "bu kodu neden böyle yazmışız?" sorusu cevaplanamıyor.

Karar Kaydı Nedir?

Yazılım mühendisliğinde ADR (Architecture Decision Record) olarak bilinen yaklaşım basit bir fikre dayanıyor: her önemli teknik karar yapılandırılmış bir formatta kayıt altına alınmalı.

ADR'nin geleneksel hali doküman ağırlıklı ve kurumsal. Startup'lar için bu format çok ağır. Ama temel fikir değerli: karar alındığı anda, bağlamıyla birlikte kaydedilmeli.

Alios'ta bu fikir node açıklamalarına taşınıyor. Ayrı bir araç, ayrı bir sistem yok — görevlerin yaşadığı yerde kararlar da yaşıyor.

Alios'ta Karar Node'u Formatı

Her teknik karar için ayrı bir node açılıyor. Bu node görev değil — kayıt. Kapatılmıyor, arşivleniyor.

📌 KARAR — [Konunun kısa başlığı]
Durum: Aktif / Revize Edildi / Geçersiz
Tarih: [Karar tarihi]
Karar Alanlar: [İsimler veya roller]

🔍 BAĞLAM
[Bu karar neden gerekli oldu? Hangi problem veya
gereksinim bu kararı tetikledi? 2-3 cümle.
Teknik olmayan biri de anlayabilmeli.]

⚖️ DEĞERLENDİRİLEN SEÇENEKLER

Seçenek A: [İsim]
Artıları: [Maddeler]
Eksileri: [Maddeler]

Seçenek B: [İsim]
Artıları: [Maddeler]
Eksileri: [Maddeler]

Seçenek C: [İsim — elenme sebebiyle birlikte]
Neden elendi: [1-2 cümle]

✅ ALINAN KARAR
[Hangi seçenek seçildi — tek cümle]

Gerekçe:
[Neden bu seçenek? Hangi kısıtlar, öncelikler veya
trade-off'lar bu kararı şekillendirdi? 3-5 cümle.
Bu bölüm en kritik kısım — gerekçesiz karar kaydı
yarım kalır.]

⚠️ KABUL EDİLEN TRADE-OFF'LAR
[Bu kararla birlikte ne kaybediyoruz veya ne riski
kabul ediyoruz? Dürüst yazılmalı.]

📎 REFERANSLAR
[İlgili node'lar, PR'lar, benchmark'lar, makaleler]

🔄 REVİZYON KOŞULU
[Bu karar ne zaman gözden geçirilmeli?
Hangi koşulda değiştirilmeli?]

Örnek: Veritabanı Seçim Kararı

Şablonun dolu hali:

📌 KARAR — Birincil Veritabanı Seçimi
Durum: Aktif
Tarih: 14 Mart 2025
Karar Alanlar: CTO, Lead Backend Dev, Kurucu

🔍 BAĞLAM
MVP için basit bir veri modeli yeterliydi ve SQLite
kullandık. Kullanıcı sayısı 500'ü geçince sorgu
süreleri arttı, eş zamanlı yazma sorunları çıktı.
Ölçeklenebilir bir veritabanına geçiş gerekli.
Aynı zamanda ekibin SQL deneyimi güçlü,
NoSQL deneyimi sınırlı.

⚖️ DEĞERLENDİRİLEN SEÇENEKLER

Seçenek A: PostgreSQL
Artıları: Güçlü SQL desteği, JSONB ile esnek şema,
ekip deneyimi var, açık kaynak, yönetilen servisler mevcut
Eksileri: Yatay ölçekleme karmaşık, NoSQL esnekliği yok

Seçenek B: MongoDB
Artıları: Esnek şema, yatay ölçekleme kolay,
document model mevcut veri yapımıza uygun
Eksileri: Ekip deneyimi yok, transaction desteği
PostgreSQL kadar güçlü değil, migration maliyeti yüksek

Seçenek C: MySQL
Neden elendi: PostgreSQL ile benzer özellikler sunuyor
ama JSON desteği daha zayıf. Ekipte PostgreSQL
deneyimi olduğundan MySQL'in avantajı yok.

✅ ALINAN KARAR
PostgreSQL seçildi, Railway üzerinde yönetilen servis.

Gerekçe:
Ekibin mevcut SQL deneyimi öğrenme maliyetini sıfıra
indiriyor. JSONB desteği şema esnekliği sağlıyor,
tam NoSQL'e geçmeye gerek kalmıyor. Railway üzerinde
yönetilen servis DevOps yükünü azaltıyor. Mevcut veri
modeli ilişkisel — PostgreSQL bu yapıya daha uygun.
MongoDB'nin esnekliği şu an ihtiyacımız olmayan bir
avantaj, öğrenme maliyeti karşısında değerini yitiriyor.

⚠️ KABUL EDİLEN TRADE-OFF'LAR
Yatay ölçekleme ileride karmaşıklaşabilir. 10M+ kayıt
aşılırsa sharding değerlendirilmeli. Bu riski şimdilik
kabul ediyoruz çünkü o ölçeğe ulaşmak önce diğer
darboğazları çözmeyi gerektiriyor.

📎 REFERANSLAR
Node: "Veritabanı Migration Planı"
Node: "Railway Altyapı Kurulumu"
Benchmark: [İç test sonuçları linki]

🔄 REVİZYON KOŞULU
Aktif kullanıcı 50.000'i geçerse veya sorgu süresi
ortalama 500ms'yi aşarsa bu karar gözden geçirilmeli.

Arama ve Linkleme: Kararları Bulmak

Karar kaydı yazmak yeterli değil — bulunabilir olması gerekiyor. Alios'ta bunun iki yolu var.

Arama: Node başlıkları ve açıklamalarında arama çalışıyor. "PostgreSQL" yazdığında o kelimeyi içeren tüm node'lar listeleniyor. Yeni geliştirici "neden PostgreSQL?" diye merak ettiğinde aramayı çalıştırıyor, karar node'unu buluyor.

Bu yüzden karar node'larında anahtar kelimeleri doğal olarak kullanmak önemli. Teknoloji adları, konu başlıkları, etkilenen sistem adları — bunlar açıklamada geçtiğinde aranabilir oluyor.

Linkleme: Karar node'unu ilgili görev node'larına referans olarak ekliyorsunuz. Bir geliştirici veritabanıyla ilgili bir görev açtığında açıklamada "ilgili karar: Birincil Veritabanı Seçimi" satırını görüyor. Tıklıyor, kararı okuyor, bağlamla birlikte işe başlıyor.

Bu linkleme alışkanlığı zamanla ekibin bilgi grafiğini oluşturuyor. Kararlar görevlerle, görevler epiklerle, epikler hedeflerle bağlanıyor.

Karar Node'larını Organize Etmek

Tüm karar node'larını tek bir üst node altında toplamak arama ve gezinmeyi kolaylaştırıyor:

📁 TEKNİK KARARLAR
├── 📌 KARAR — Birincil Veritabanı Seçimi
├── 📌 KARAR — Frontend Framework Seçimi
├── 📌 KARAR — Kimlik Doğrulama Yaklaşımı
├── 📌 KARAR — Deployment Stratejisi
├── 📌 KARAR — API Versiyonlama Standardı
└── 📌 KARAR — Loglama ve İzleme Altyapısı

Bu liste ekibin "neden böyle yapıyoruz?" sorularının merkezi oluyor. Onboarding'de yeni geliştiriciye ilk gösterilen şeylerden biri.

Hangi Kararlar Kayıt Altına Alınmalı?

Her küçük teknik tercih için karar node'u açmak gerekmiyor. Şu kriterleri karşılayan kararlar kaydedilmeli:

Geri dönmesi maliyetli olanlar — veritabanı seçimi, framework tercihi, API tasarımı. Tartışmalı olanlar — ekipte görüş ayrılığı yaratan, alternatifler değerlendirilen. Bağlamı olmadan anlaşılmayanlar — "neden böyle yapmışız?" sorusunu tetikleyecek her şey. Başka kararları etkleyenler — bir kararın başka teknik tercihler üzerinde kısıt yarattığı durumlar.

Küçük implementasyon detayları, kod stili tercihleri, araç konfigürasyonları karar node'u gerektirmiyor — bunlar kod yorumlarına veya README'ye ait.

Son Düşünce

Teknik dokümantasyon yönetimi "sonra yapacağız" listesinde kalıyor çünkü anlık değeri görünmüyor. Ama altı ay sonra, yeni bir geliştirici geldiğinde veya önemli bir mimari değişiklik tartışıldığında o belgelerin değeri net ortaya çıkıyor.

Alios'ta karar node'larını görevlerle aynı sistemde tutmak bu belgeleri "ayrı bir yerde duran doküman" olmaktan çıkarıyor. Kararlar işin içinde yaşıyor, linklerle bağlanıyor, arama yapılabiliyor.

"Neden böyle karar verdik?" sorusu artık toplantı gerektirmiyor. Node açılıyor, cevap orada duruyor.