Altyapı Olarak Dokümantasyon: Mühendislik Takımlarında Bilgiyi Ölçeklendirme

Dokümantasyon borcu, mühendislik takımlarını yanlış kişi ayrılana kadar fark edilmeyen şekillerde yavaşlatır. Maliyet bir ödeme olayında, bir migration’da ya da bir denetimde ortaya çıkar: yazılı prosedür mevcuttur ama derin sistem anlayışı yoktur. O anı atlatan dokümantasyonun üç katmanı vardır: RFC ve ADR olarak yakalanan kararlar, sistemlerin kendisinden türetilen sistem referansı ve gerçek örneklerle yazılmış süreç dokümanları. Geri kalan her şey, bu üç katmanı güncel tutan araçlar ve inceleme alışkanlıklarıdır.

Wiki Mezarlıkları ve README Ruleti#

Araç ne olursa olsun aynı şekiller tekrar ediyor. Bir Confluence alanı binlerce sayfaya çıkıyor ve çoğu bayatlıyor; “kimlik doğrulama” araması yüzlerce sonuç döndürüyor, hangisinin güncel olduğunu anlamanın yolu yok. Her repository kendi standardını koyduğu için README kalitesi mükemmelden hiç yoka kadar değişiyor, yeni mühendisler hangi dosyaya güveneceğini tahmin ediyor. Bu tahmini bitirecek mimari karar ise genelde kimsenin bulamadığı bir #general konuşmasında ya da kimsenin okuyamadığı bir özel mesajda duruyor.

Bir de billing sistemi var; onu tam olarak tek kişi biliyor. Gün boyu bu sistemle ilgili soruları o yanıtlıyor, ayrıldığında bilgi de onunla gidiyor. Yazıya dökülenler de çoğu zaman ortak formatı olmayan yüzlerce Google Doc’a dağılıyor; “bu neden böyle tasarlanmış” sorusu arkeoloji işine dönüyor.

Kullanılan araç, takımın bilgi mimarisine nasıl yaklaştığından çok daha az belirleyicidir. Confluence veya Notion’a sayfa eklemek bunu çözmez; sahiplik ve inceleme süreci tanımlanmadan iyi yapılandırılmış bir wiki bile hızla eskir.

Dokümantasyon Borcu ve Teknik Borç#

Teknik borcu konuşmaya çok zaman harcıyoruz, ama dokümantasyon borcunu fark etmek daha zordur. Teknik borç genellikle daha yavaş deployment’larda veya zor bakımda görünür. Dokümantasyon borcu, takımlar altı ay önce aldıkları kararları sorgulamaya başladığında ortaya çıkar çünkü kimse mantığı hatırlamaz.

Maliyet üç yerde birikir. Günlük düzeyde adaptasyon süresine, kıdemli mühendislerin soğurduğu kesintilere ve iki takımın birbirinden habersiz aynı sorunu çözmesine yansır. Bunun altında daha sessiz maliyetler durur: organizasyonun daha önce yaptığı hataları tekrarlamak ve kimsenin açıklayamadığı sistemlere dokunmaktan çekinmek. Kriz anında ise sistemi bilen kişiye ulaşılamadığı için uzayan bir olaya ya da bir kontrolün neden öyle tasarlandığını kimsenin yeniden kuramadığı bir denetime dönüşür.

Üç Katmanlı Bir Dokümantasyon Yaklaşımı#

Her katmanın güncellenme ritmi farklıdır; ayrı tutmanın gerekçesi de budur:

Karar Kaydı#

Seçimlerin ardındaki mantık burada durur. Ne inşa ettiğiniz değil, neden o şekilde inşa ettiğiniz.

/docs
  /decisions  # ADR'ler - alınan mimari kararlar
  /proposals  # RFC'ler - düşünülen gelecek değişiklikler  
  /discussions  # RFD'ler - araştırılan açık problemler

Dokümanın boyutunu etkinin yarıçapına göre seçin. Geri döndürülebilir, tek takımı ilgilendiren bir karar için bir hafta içinde kapanan 1-2 sayfalık mini-RFC yeter. Ciddi yatırım gerektiren çok takımlı bir değişiklik 5-10 sayfayı ve 2-4 haftalık incelemeyi hak eder. Şirket çapındaki mimari değişimler her iki kalemde de daha uzun sürer.

Kendini Yenileyen Sistem Referansı#

Bu mevcut gerçekliğinizi tanımlar. Ne var, nasıl bağlanıyor, kimin sorumluluğunda.

/systems
  /service-catalog  # Hangi servisler var, kimin sorumluluğunda
  /architecture  # Sistemler nasıl bağlanıyor ve iletişim kuruyor
  /runbooks  # Nasıl işletilir ve sorun giderilir
  /dependencies  # Ne neye bağımlı

Bu katman çoğunlukla otomatikleştirildiğinde işe yarar. Elle yazılan sistem dokümanları tamamlandıkları anda bayatlamaya başlar. OpenAPI şemalarından, Terraform state’inden veya CI pipeline’lardan türetilen dokümantasyon ise değişikliklerle birlikte güncellenir.

Örneklerden Yazılan Süreç Dokümanları#

Nasıl çalışıyorsunuz, nasıl karar veriyorsunuz, olaylara nasıl müdahale ediyorsunuz.

/processes
  /engineering  # Nasıl tasarlar, inşa eder ve gözden geçiririz
  /oncall  # Olaylara nasıl yanıt veririz
  /releases  # Nasıl deploy eder ve geri alırız
  /hiring  # Nasıl değerlendirir ve adapte ederiz

Burada somut örnekler soyut yönergelerden daha çok işe yarar. Bir olayın pratikte nasıl ele alındığını anlatan bir örnek, yeni bir mühendise ilkeler listesinden daha fazla tutamak verir.

Tasarım Dokümanı Formatı#

Google’ın tasarım dokümanı kültürü, bu yaklaşımın yayımlanmış rehberi bulunan hâli: akran incelemesinden geçen, tartışması yorumlarda yürüyen işbirlikçi bir teknik belge. Ağırlığı taşıyan unsurlar:

• Bağlam ve Kapsam - Neyi çözüyoruz?
• Hedefler ve Hedef Olmayanlar - Başarının nasıl göründüğü
• Tasarım - Nasıl çözeceğiz
• Alternatifler - Neyi düşündük ve reddettik
• Kesişen Kaygılar - Güvenlik, performans, izleme

Takımların atladığı bölüm Alternatifler oluyor. O bölüm olmadan sonraki okuyucu, bariz seçeneğin değerlendirilip mi elendiğini yoksa hiç akla mı gelmediğini bilemez.

Dokümantasyonu CI’da Doğrulamak#

Bir doküman ağacını dürüst tutan kontroller, kodla aynı pipeline’a aittir:

# .github/workflows/docs.yml
name: Dokümantasyon Altyapısı
on:
  pull_request:
    paths: ['docs/**', 'adr/**', 'rfcs/**']

jobs:
  validate-documentation:
    runs-on: ubuntu-latest
    steps:
      - name: RFC formatını doğrula
        run: |
          # Gerekli bölümlerin var olduğunu kontrol et
          # YAML frontmatter'ı doğrula
          # Karar durumunun geçerli olduğunu sağla
      
      - name: Kırık linkleri kontrol et
        run: |
          # Ölü iç linkler için tara
          # Dış linklerin 200 döndürdüğünü doğrula
          # Deprecated servislere linkleri işaretle
          
      - name: Mimari diyagramları üret
        run: |
          # PlantUML kaynaklarından otomatik üret
          # Sistem bağımlılık grafiklerini güncelle
          # Görsel servis haritaları oluştur
          
      - name: Arama dizinini güncelle
        run: |
          # Yeni içeriği aranabilirlik için indeksle
          # Belgeleri metadata ile etiketle
          # Öneri motorunu güncelle

Pratikte iyi çalışan tool stack:

• MkDocs Material - Güzel, aranabilir dokümantasyon siteleri
• PlantUML/Mermaid - Versiyon kontrollü mimari diyagramları
• ADR-tools - Komut satırı karar kaydı yönetimi
• GitHub Actions - Otomatik doğrulama ve yayınlama

Dokümantasyon Kararları için DACI Çerçevesi#

Herhangi bir önemli teknik karar için DACI çerçevesi (Driver, Approver, Contributors, Informed) rolleri netleştirir:

# RFC-042: Veritabanı Taşıma Stratejisi

## DACI Matrisi
- **Driver:** Veritabanı Takım Lideri
  - Girdi toplama ve karara ulaşmadan sorumlu
  - Zaman çizelgesi ve sürece sahip
  
- **Approver:** VP Mühendislik  
  - Son kararı verir
  - Sonuçtan sorumlu
  
- **Contributors:** Backend Takımları, SRE, Güvenlik, Data Engineering
  - Girdi ve uzmanlık sağlar
  - Karardan etkilenecek
  
- **Informed:** Tüm Mühendislik, Ürün, Finans
  - Sonucu bilmesi gereken
  - Planlarını ayarlaması gerekebilir

## Karar Zaman Çizelgesi
- **1. Hafta:** Paydaş görüşmeleri ve gereksinim toplama
- **2. Hafta:** Teknik değerlendirme ve kavram kanıtları
- **3. Hafta:** Maliyet analizi ve taşıma planlaması
- **4. Hafta:** Son karar ve iletişim

Bu çerçeve “çok aşçı” durumunu önlemeye yardımcı olurken insanların duyulduğunu hissettirmesini de sağlar. Doğru dengeyi bulmak biraz deneme yanılma gerektirir.

Dokümantasyon Şampiyonları#

Dokümantasyon kültürü yukarıdan emredilmeye pek gelmez; ya büyür ya büyümez. Düzenlenebilecek olan şey koşullardır. İşe yarayan düzenlemelerden biri, her takımda bir dokümantasyon şampiyonu belirlemek: RFC incelemelerini yürüten, yeni sistemlerin dokümanla birlikte geldiğini kontrol eden, açıkları ve bayat sayfaları işaretleyen, şablonlar konusunda takım arkadaşlarına koçluk yapan kişi. Haftada birkaç saati geçmez ve kalıcı bir ikinci işe dönüşmeden el değiştirmelidir.

Sorunu Önceden Haber Veren Metrikler#

Birçok takım dokümantasyon sağlığıyla mutlaka korele olmayan şeyleri takip eder. Pratikte ölçülmesi daha yararlı olan metrikler şunlardır:

interface DokümantasyonSağlığı {
  // Öncü göstergeler (gelecek problemleri tahmin eder)
  rfcKatılımı: number;  // RFC incelemelerine katılan mühendis %'si
  dokGüncellemeSıklığı: number;  // Son güncellemeden ortalama gün
  bilgiDağılımı: number;  // >1 uzmanı olan sistem %'si
  
  // Gecikmeli göstergeler (mevcut durumu ölçer)
  adaptasyonHızı: number;  // İşe alımdan ilk commit'e gün
  çaprazTakımSoruları: number;  // Çapraz takım bilgisi gerektiren sorular
  
  // Kalite göstergeleri (dokümantasyon değerini ölçer)
  dokümanErişimi: number;  // Son 90 günde erişilen dok %'si
  linkSağlığı: number;  // Çalışan iç link %'si
  aramaBaşarısı: number;  // Cevap bulan arama %'si
}

Aylık incelemede sorulmaya değer sorular şunlar: hangi bilgi açıkları gecikmelere yol açtı, hangi sorular birden fazla kez soruldu, hangi belgeler bayatlıyor ve insanlar cevabı dokümantasyon sisteminin dışında nerede arıyor.

Dokümantasyonun Sonucu Değiştirdiği Yerler#

Nöbetteki mühendis çoğu zaman geri alma prosedürünü daha önce hiç çalıştırmamış kişidir ve sistemi kuran kişiye o gece ulaşılamayabilir. Bir runbook, bu baskı altında hâlâ işe yarayacak kadar sık prova edildiğinde ve güncellendiğinde yerini hak eder.

Satın alma veya yeniden yapılanma sonrası entegrasyonlar aynı problemi daha yavaş bir saate yayar. Takvimin çoğu, karşı tarafın işleri neden o şekilde kurduğunu yeniden çıkarmaya gider. O gerekçe ADR ve tasarım dokümanı olarak zaten yazılıysa bu adım plandan düşer ve taşıma işi daha erken başlar.

Denetimler aynı soruyu yazılı olarak sorar. Denetçiler erişim kontrolleri ve veri işleme kararlarının neden öyle tasarlandığını bilmek ister; mevcut yapılandırma tek başına bu gerekçeyi taşımaz, gerekçeyi taşıyan şey ADR zinciridir. Zincir yoksa takım kendi gerekçesini denetim saati işlerken hafızadan toparlamaya çalışır.

Dokümantasyon Aracını Seçmek#

Seçimi çoğunlukla kısıtlar belirler. Sıkı bir Jira bağımlılığı ya da bir uyumluluk şartı sizi Confluence’a bağlar. Üçüncü parti SaaS’i engelleyen bir güvenlik politikası SharePoint’e mahkûm eder. Geriye kalanı kimin yazdığı ve kimin okuduğu belirler: ürün dokümanları PM’lerin zaten çalıştığı yere, API dokümanları OpenAPI şemalarından senkronlanabildiği yere, mühendislik kararları da onları uygulayan kodun yanına gider.

Kurumsal Wiki’yi Yaşanabilir Kılmak#

Confluence veya SharePoint zorunluysa, acının çoğu alanın nasıl düzenlendiğinden gelir. Space’leri hedef kitleye göre ayırın ki mühendislik RFC’leri ile ürün PRD’leri aynı arama indeksini paylaşmasın. Sayfa başlığına tarihi koyun ([2024-01-22] Database Migration RFC); kötü bir arama sonucundan sonra ayakta kalan şey kronolojidir. Her sayfa tipini şablonlayın, eski sayfaları label’la arşivleyin ki güncel olanlarla yarışmasınlar ve OneNote’u wiki rolünden uzak tutun; araması bu yükü kaldırmıyor. SharePoint tarafında versiyon kontrolünü checkout/checkin, onayları Power Automate karşılar.

Servis Kataloğu Kayıtları#

Backstage, “bu hangi servis ve kimin sorumluluğunda” sorusunun bariz bir cevabı kalmadığında değer üretmeye başlar. Katalog kaydının kendisi dokümantasyondur ve servisin repository’sinde durur:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment processing
  annotations:
    docs: https://docs.internal/payment
    pagerduty: PD123
spec:
  type: service
  owner: platform-team
  lifecycle: production

Araç Seçim Matrisi#

Use Case	İlk Tercih	Alternatif	Kaçının
Engineering RFC’ler	GitHub + MkDocs	GitBook	SharePoint
Product Dokümantasyon	Notion	Confluence	Word Docs
API Docs	GitBook	Backstage	Wiki
Runbooks	MkDocs	Confluence	OneNote
Knowledge Base	Obsidian	Notion	Folders
Service Catalog	Backstage	Custom	Excel

Confluence’tan Linkleri Kırmadan Çıkmak#

Takımların atladığı adım yönlendirme haritası. O olmadan, Slack konuşmalarına yapıştırılmış bütün linkler ve tarayıcı yer imleri taşıma günü ölür:

# 1. Export Confluence space
confluence-export --space ENG --format markdown

# 2. Transform to MkDocs structure
python transform_confluence.py --input export/ --output docs/

# 3. Setup redirects for old URLs
# mkdocs.yml
plugins:
  - redirects:
      redirect_maps:
        'old-page.md': 'new-structure/page.md'

Çoğu Takımın Ulaştığı Yapı#

Çoğu organizasyon birden fazla tool kullanır:

documentation_stack:
  decisions:
    tool: GitHub + ADR-tools
    reason: "Version control ve code review"
  
  product_specs:
    tool: Notion
    reason: "PM'ler için kolay, zengin formatlar"
  
  runbooks:
    tool: Confluence
    reason: "On-call mühendisler alışık"
  
  api_docs:
    tool: GitBook
    reason: "Auto-sync with OpenAPI specs"
  
  knowledge_base:
    tool: Obsidian
    reason: "Bağlantılı bilgi grafiği"

Bölünmüş bir yapı, ancak hangi aracın neyi tuttuğunu herkes bildiğinde işe yarar. “RFC nerede?” sorusunun, takımdaki herkesin önce birkaç sistemi taramadan verebileceği tek bir cevabı olmalı.

Tutarlılık ve Güncellik#

Ortak şablonlar ve ortak bir inceleme yolu, her takımın kendi formatını icat etmesinden daha iyi ölçeklenir. Bir RFC’nin şeklini bilen okuyucu, hiç çalışmadığı takımların yazdıklarında bile yolunu bulur.

Güncellik cilalı olmaktan önemlidir. Düzenli güncellenen makul bir belge, bayatlamış mükemmel bir belgeyi geçer; o yüzden emek, güncellemeyi ucuzlatmaya harcanmalıdır: hâlihazırda var olan bir toplantının içinde bir inceleme aralığı, pipeline’da bir link denetimi, sayfada adı yazan bir sahip.

Bu Yaklaşım Ne Zaman Karşılığını Verir#

Dokümantasyon altyapısı; bilgi devir hızının yüksek olduğu, sistemlerin tek bir kişinin kavrayamayacağı kadar karmaşıklaştığı ya da yeni üye adaptasyonunun sürekli sorun çıkardığı takımlarda gerçekten karşılığını veriyor. Tek mühendislik projelerinde veya kısa ömürlü prototiplerde bakım maliyeti faydanın önüne geçiyor. Makul bir ilk adım, bu çeyrekte en çok karışıklığa yol açan kararı belgeleyen tek bir ADR yazmak.

Kaynaklar#

• Diátaxis Çerçevesi (yeni sekmede açılır) - Kullanıcı ihtiyacına göre öğretici, nasıl yapılır kılavuzu, referans ve açıklamayı birbirinden ayıran teknik dokümantasyona sistematik yaklaşım
• Yazılım Dokümantasyon Kılavuzu - Write the Docs (yeni sekmede açılır) - Uygulayıcıların dokümantasyon süreci, araçları ve en iyi pratikleri kapsayan topluluk tarafından sürdürülen kılavuz
• Mimari Karar Kayıtları (yeni sekmede açılır) - Mimari kararları yakalamak ve izlemek için ADR formatları, şablonlar (MADR dahil) ve araçlar için referans merkezi
• Dokümantasyon En İyi Pratikleri - Google Stil Kılavuzları (yeni sekmede açılır) - Kod olarak dokümantasyon prensipleri ve güncellik pratiklerini içeren Google’ın mühendislik dokümantasyon yönergeleri
• Google’da Yazılım Mühendisliği - Dokümantasyon Bölümü (yeni sekmede açılır) - Google SWE kitabından dokümantasyonun ölçekte kod gibi nasıl ele alındığına dair derinlemesine bölüm