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

Eksik Dokümantasyon Beklenenden Pahalıya Malolduğunda

Kritik sistemi anlayan son mühendis ayrıldığında, dokümante edilmiş prosedürlerle gerçek sistem anlayışı arasındaki boşluk ilk kriz anında görünür hale gelir.

Bir takım pahalıya mal olan bir öğrenme anıyla karşılaşır. Üç senior mühendis altı ay içinde ayrılır - normal kariyer gelişimi, dramatik bir şey değil. Tüm “doğru” şeyler yapılmış olmasına rağmen (devir-teslim, bilgi transfer oturumları, dokümantasyon sprintleri), ödeme sistemi en büyük satış hafta sonunda sorun yaşadığında, dokümante edilmiş prosedürlerle derin sistem anlayışı arasındaki boşluk ortaya çıkar.

Kurtarma beklenenin çok üzerinde sürer: yaklaşık 18 saat stresli mühendisler, endişeli yöneticiler ve neler olduğunu merak eden müşteriler. Gelir etkisi önemlidir, ama daha büyük ders bilgi mimarisinin ne kadar kırılgan hale geldiğidir.

Bu deneyim önemli bir gerçeği ortaya koyar: Dokümantasyon sadece bir şeyleri yazmakla ilgili değil. Herhangi bir mühendisten daha uzun yaşayabilecek bilgi sistemleri inşa etmekle ilgili.

Yaygın Dokümantasyon Desenleri

Farklı takımlarda tekrarlanan bazı zorluklar var:

Seviye 1: Wiki Mezarlığı

• Confluence’ta 10.000 sayfa
• %90’ı güncel değil veya alakasız
• “Kimlik doğrulama” araması 847 sonuç döndürüyor
• Hangisinin güncel olduğunu kimse bilmiyor

Seviye 2: README Ruleti

• Her repository farklı dokümantasyon standardına sahip
• Kalite mükemmelden hiç yoktan değişiyor
• Yeni mühendisler hangi README’ye güvenecekleri konusunda tahmin oyunu oynuyor

Seviye 3: Slack Bilgisi

• Kritik mimari kararlar #general’da gömülü
• “Database migration hakkındaki o konuşmayı hatırlıyor musun?” Hayır, kimse hatırlamıyor
• Kurumsal bilgi özel mesajlarda tuzağa düşmüş

Seviye 4: Kahraman Dokümantasyonu

• Billing sistemi hakkında her şeyi bilen tek kişi
• Sorularla aşırı yüklenmiş durumda
• Ayrıldıklarında, bilgi kapıdan çıkıp gidiyor

Seviye 5: Toplantı Tutanakları Labirenti

• Önemli kararlar yüzlerce Google Doc’a dağılmış
• Tutarlı format veya yapı yok
• Bir tasarım seçiminin gerekçesini bulmak arkeolojik beceri gerektiriyor

Bunlardan herhangi biri tanıdık geliyorsa, yalnız değilsin. Sorun genellikle hangi araçların kullanıldığıyla değil, bilgi mimarisine nasıl yaklaşıldığıyla ilgilidir. Confluence veya Notion’a daha fazla sayfa eklemek sorunu çözmez; net karar yapıları (ADR’ler, RFC’ler) ve sahiplik modelleri başarı için kritiktir. Ownership tanımlamadan ve review süreçleri olmadan iyi yapılandırılmış wiki’ler bile hızla eskir. Kod değişikliklerinde olduğu gibi dokümantasyonda da review, versiyonlama ve net sorumluluklar uzun vadede bakım yükünü azaltır.

Dokümantasyon Borcu: Sessiz Organizasyon Katili

Teknik borç hakkında çok zaman harcıyoruz konuşarak, ama dokümantasyon borcu fark edilmesi daha zor olabiliyor. 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.

Maliyetler genellikle şu alanlarda ortaya çıkıyor:

interface DokümantasyonBorcuMaliyeti {
  // Anında maliyetler
  adaptasyonSüresi: '6 hafta → düzgün dokla 2 hafta';
  günlükKesintiler: '40 Slack sorusu → 5 soru';
  tekrarlananİş: '3 takım aynı sorunu bilmeden çözüyor';
  
  // Gizli maliyetler  
  kötüKararlar: 'Geçmiş hataları tekrarlama';
  analizFelci: 'Dokümantasyonsuz sistemleri değiştirmekten korku';
  yetenekKaybı: 'Senior mühendisler insan dokümantasyonu oluyor';
  
  // Kriz maliyetleri
  prodüksiyonOlayları: '%60'ı bilgi açığından kaynaklanıyor';
  denetimBaşarısızlıkları: 'Uyumluluk kararlarını kanıtlayamama';
  satınAlmaEntegrasyonu: '6 ay yerine 18 ay';
}

Dokümantasyonu “ekstra iş” olarak gören takımlar genellikle aynı bilgileri defalarca açıklayarak ve yeniden keşfederek daha fazla zaman harcar. Bu maliyet genellikle bütçe satırında görünmez; yine de her tekrarlanan açıklama ve her yeniden keşfedilen karar, toplam organizasyonel maliyete eklenir.

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

Pratikte makul biçimde ölçeklenen üç katmanlı bir yaklaşım öne çıkıyor:

Katman 1: Karar Mimarisi (Neden)

Bu, seçimlerin ardındaki mantığı yakaladığınız yer. 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

İyi çalışan şablon yaklaşımı:

Mini-RFC (1-2 sayfa):

• Tek takım etkisi
• Geri döndürülebilir kararlar
• 1 haftalık zaman çizelgesi

Standart RFC (5-10 sayfa):

• Çoklu takım etkisi
• Önemli yatırım
• 2-4 haftalık zaman çizelgesi

Stratejik RFC (10+ sayfa):

• Şirket çapında etki
• Büyük mimari değişiklikler
• 6+ haftalık zaman çizelgesi

Katman 2: Sistem Dokümantasyonu (Ne)

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ı

Pratikte önemli bir nokta: Bu katman çoğunlukla otomatikleştirildiğinde en iyi şekilde çalışır. 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 ve doğruluğunu korur.

Katman 3: Süreç Dokümantasyonu (Nasıl)

Bu kültürel DNA’nızı yakalar. 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

Yararlı bir desen: Süreç dokümanları soyut yönergelere değil somut örneklere dayandığında daha iyi çalışır. “İşte pratikte yapılan şey” ifadesi, “işte yapılması gereken şey”den daha iyi öğretir.

Amazon vs Google Dokümantasyon Felsefesi

Büyük organizasyonlarda sık sık iki ana yaklaşım öne çıkıyor:

Amazon’un Anlatı Yaklaşımı

PowerPoint sunumları yerine 6 sayfalık yazılı anlatılar:

• Toplantılardan önce tam düşünmeyi zorlar
• Karar sürecinin eserini yaratır
• “Study hall” formatı herkesin gerçekten okumasını sağlar

Yaygın olarak kullanılan yapı (sonuçlar takıma göre değişir):

1. Yönetici Özeti (1 sayfa)
2. Bağlam ve Problem (1 sayfa)
3. Önerilen Çözüm (2 sayfa)
4. Düşünülen Alternatifler (1 sayfa)
5. Uygulama Planı (1 sayfa)
6. Ek (sınırsız)

Google’ın Tasarım Dokümanı Kültürü

Akran incelemeli işbirlikçi teknik belgeler:

• Trade-off’lar ve alternatiflere vurgu
• Sistem bağlam diyagramları
• Yorumlar aracılığıyla asenkron işbirliği

Ana 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

Yararlı bir hibrit: Amazon’ın “kendini düşünmeye zorla” yaklaşımını Google’ın işbirlikçi inceleme kültürüyle birleştirmek iyi sonuç verebilir. Farklı takım dinamikleri farklı yaklaşımlara daha iyi yanıt verdiğinden, sonuçlar değişir.

Kod Olarak Dokümantasyon: Teknik Uygulama

Dokümantasyonu diğer kritik altyapı gibi ele alın:

# .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, Amazon’un DACI çerçevesi dokümantasyon süreci etrafında netlik sağlar:

# 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ı ayarlamayı 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 Kültürünü Ölçeklendirme: Şampiyon Ağı

Dokümantasyon kültürü gerçekte yukarıdan emredilemez; daha doğal büyüdüğünde daha iyi çalışır. Kök salmasını daha olası kılan koşullar ise oluşturulabilir.

Dokümantasyon Şampiyonu Yaklaşımı

Her takım için bir “Dokümantasyon Şampiyonu” bulundurmak iyi çalışır (genellikle şampiyon başına yaklaşık 5-8 mühendis):

Sorumluluklar:

• Takımları içinde RFC incelemelerini kolaylaştırır
• Yeni sistemlerin uygun dokümantasyonla gelmesini sağlar
• Bilgi açıklarını ve güncel olmayan bilgileri identify eder
• Takım üyelerini dokümantasyon standartları konusunda coachlar

Zaman taahhüdü: Haftada ~2 saat Rotasyon: Tükenmişliği önlemek için her 6 ayda bir

Gerçekten Önemli Olan Dokümantasyon Metrikleri

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ümantRelevanslığı: number;  // Son 90 günde erişilen dok %'si
  linkSağlığı: number;  // Çalışan iç link %'si
  aramaBasarısı: number;  // Cevap bulan arama %'si
}

Aylık inceleme soruları:

1. Bu ay hangi bilgi açıkları gecikmelere neden oldu?
2. Hangi sorular birden çok kez soruldu?
3. Hangi belgeler bayatlıyor?
4. İnsanlar dokümantasyon sistemimizin dışına nerede gidiyor?

İyi Dokümantasyonun Gerçekten Fark Yarattığı Zamanlar

Dokümantasyon Bir Hafta Sonunu Kurtardığında

Büyük bir alışveriş hafta sonunda veritabanı taşıması yarı yolda takılıp kaldı. Geri alma sürecini en iyi bilen mühendis dünyanın diğer tarafında tatildeydi.

Detaylı runbook’lar (dikkatle test edilmiş ve güncellenmiş) olmasa saatlerce büyük sorun yaşanırdı. Nöbetçi takım dokümante edilmiş kurtarma sürecini takip ederek işleri nispeten hızlı yoluna koyabildi.

İş etkisi önemli olabilirdi. Daha da önemlisi, takım orijinal uzman mevcut olmasa da durumu halledebileceğine güvendi.

Şaşırtıcı Derecede Pürüzsüz Geçen Bir Satın Alma

Yaklaşık 50 kişilik bir mühendislik takımı bünyeye katıldı. Satın almalar genellikle sistemleri ve pratikleri anlamaya çalışmakla geçen 12-18 aylık bir entegrasyon maratonuna dönüşür.

Bu vakayı farklı kılan şey satın alınan takımın dokümantasyon alışkanlıklarıydı. Sağlam RFC ve ADR pratikleri, büyük sistemleri için tasarım dokümanları ve en önemlisi mimari kararlarının arkasındaki mantık; hepsi yakalanmış ve erişilebilir durumdaydı.

Entegrasyon çaba gerektirdi; satın almalar her zaman gerektirir. Ama süre tipik bir yılın üzerindeki zaman çizelgesi yerine aylarda kaldı. Mühendisler yeni sistemlerde çok daha hızlı verimli hale gelebildi çünkü kaynak sistemler anlaşılabilirdi.

Dokümantasyon kalitesi, günlük mühendislik verimliliğinin ötesinde iş sonuçlarını doğrudan etkiler.

Denetçiler Dokümantasyonu Övdüğünde

SOC2 Type II denetiminde denetçiler mimari kararları, özellikle veri işleme ve erişim kontrollerini anlamak istedi.

Karar gerekçelerini yeniden yapılandırmanın olağan telaşı yerine, güvenlikle ilgili mimari kararları belgeleyen birkaç yıllık ADR’ler hazırdı. Mantık, değerlendirilen alternatifler ve uygulamanın nasıl doğrulandığı; hepsi oradaydı.

Denetim süreci sorunsuz geçti. Denetçilerden biri, dokümantasyon yaklaşımının mimari seviyede güvenlik uygulamalarına güven verdiğini belirtti.

İyi dokümantasyon uygulamaları, dahili takım verimliliğinin çok ötesinde faydalar taşır.

Dokümantasyon ROI Hesaplayıcısı

Dokümantasyon yatırımının ekonomisini düşünmek için, sayılarla ilgili yardımcı olan kaba bir hesaplayıcı:

function calculateDocumentationROI(teamSize: number, avgSalary: number) {
  const engineerHourlyCost = avgSalary / (52 * 40); // $300k mühendis için ~$150/saat
  
  // Mühendis başına aylık zaman tasarrufu (muhafazakar tahminler)
  const monthlySavings = {
    hızlıAdaptasyon: 15,  // tribal knowledge'a karşı tasarruf edilen saat
    azKesinti: 10,  // soru cevaplama ile geçirilmeyen saat
    iyiDebugging: 12,  // uygun runbook'larla tasarruf edilen saat
    hızlıKararlar: 8,  // toplantı/araştırmaya karşı tasarruf edilen saat
    önlenenTekrarİş: 6,  // hataları tekrarlamaya karşı tasarruf edilen saat
  };
  
  const totalMonthlySavings = Object.values(monthlySavings)
    .reduce((sum, hours) => sum + hours, 0);
  
  const annualSavings = totalMonthlySavings * engineerHourlyCost * teamSize * 12;
  
  // Dokümantasyon yatırımı: mühendis başına ayda 4 saat
  const documentationCost = 4 * engineerHourlyCost * teamSize * 12;
  
  return {
    annualSavings,
    documentationCost,
    netBenefit: annualSavings - documentationCost,
    roi: ((annualSavings - documentationCost) / documentationCost) * 100
  };
}

// Örnek: $300k ortalama maaşla 30 kişilik takım
// Yıllık tasarruf: ~$950k
// Dokümantasyon maliyeti: ~$180k  
// Net fayda: ~$770k
// ROI: ~%428

Açıkçası, bu sayılar kaba tahminlerdir ve koşullara göre büyük farklılıklar olabilir. Yine de dokümantasyon yatırımını harcanan zaman yerine tasarruf edilen zaman açısından düşünmek yararlı bir çerçeve.

Dokümantasyon Araçları: Hangisi Ne İçin?

Çeşitli araçları denedikten sonra, farklı durumlarda neyin iyi çalıştığı hakkında bazı görüşler geliştirdim. Takımınızın ihtiyaçları farklı olabilir, ama işte gözlemlediklerim:

Confluence: Enterprise’ın Klasiği

Ne zaman işe yarar:

• Jira entegrasyonu kritikse
• Kurumsal compliance gerekliyse
• Non-technical stakeholder’lar da erişim istiyorsa

Nasıl düzgün kullanılır:

/spaces
  /ENG  # Engineering space
    /RFC  # RFC'ler için template'li sayfa ağacı
    /ADR  # Tarih bazlı ADR arşivi
    /Runbooks  # Kategorize edilmiş operasyon dokümanları
  /PRODUCT  # Product space (PRD'ler için)

Pro tip: Confluence’ta sayfa başlıklarına tarih ekleyin: [2024-01-22] Database Migration RFC. Arama çalışmıyor ama en azından kronolojik sıralama olur.

Anti-pattern’ler:

• Her şeyi tek space’e koymak (arama cehennemi)
• Template kullanmamak (tutarsız formatlar)
• Eski sayfaları silmemek (arşiv label’ı kullanın)

Notion: Modern ve Esnek

Ne zaman parlıyor:

• Database view’ları kullanmak istiyorsanız
• Kanban board’da RFC tracking yapmak için
• Rich media ve embed’lerle zengin dokümanlar için

Veritabanı tabanlı setup:

// RFC Database yapısı
interface NotionRFC {
  title: string;
  status: 'Draft' | 'Review' | 'Approved' | 'Rejected';
  author: Person;
  reviewers: Person[];
  impactedTeams: MultiSelect;
  decisionDate: Date;
  tags: MultiSelect;
}

Güçlü yanları:

• Farklı view’lar (Table, Board, Timeline, Calendar)
• Zengin template sistemi
• AI entegrasyonu (otomatik özetleme)
• Versiyon history ve collaboration

GitBook: Developer-First Yaklaşım

Mükemmel olduğu yer:

• Open source projeler
• API dokümantasyonu
• Versiyon kontrollü dokümantasyon

Git entegrasyonu:

# .gitbook.yaml
root: ./docs/
structure:
  readme: README.md
  summary: SUMMARY.md
redirects:
  previous/page: new-folder/new-page.md

Avantajları:

• GitHub/GitLab sync
• Markdown native
• Code review’dan geçebilir
• Branch’lere göre farklı versiyonlar

Obsidian: Knowledge Graph Yaklaşımı

Ne zaman kullanmalı:

• Birbirine bağlı bilgi ağı oluşturmak için
• Personal knowledge management
• Zettelkasten metodolojisi

Kurumsal kullanım:

[[2024-01-22-database-migration]]
Related: [[postgres-best-practices]] | [[migration-checklist]]
Tags: #rfc #database #approved

Graph view’un gücü: Hangi sistemlerin birbiriyle ilişkili olduğunu görsel olarak gösterir.

SharePoint/Teams Wiki: Microsoft Ekosistemi

Zorunlu olduğu durumlar:

• Microsoft 365 kullanan organizasyonlar
• Güvenlik politikaları 3rd party’yi engelliyor
• IT departmanı başka bir şeye izin vermiyor

En iyi pratikler:

/sites/Engineering
  /Shared Documents
    /Architecture
      /ADR
        /2024
          01-use-kubernetes.md
          02-migrate-to-postgres.md
    /Processes
      /RFC-Template.docx

Hayatta kalma taktikleri:

• OneNote’u wiki olarak kullanmayın (arama felaketi)
• Version control için checkout/checkin kullanın
• Power Automate ile approval workflow’ları kurun

GitHub/GitLab Wiki: Code-Adjacent Dokümantasyon

İdeal kullanım:

• Repository-specific dokümantasyon
• Contributing guidelines
• Development setup

Yapılandırma:

.wiki/
  Home.md
  Architecture/
    Decision-Records.md
    System-Overview.md
  Operations/
    Deployment.md
    Rollback.md

Backstage: Developer Portal

Enterprise scale için:

• Service catalog
• API dokümantasyonu
• Tech radar
• Cost tracking

catalog-info.yaml:

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

Tool 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

Migration Stratejisi

Confluence’tan MkDocs’a geçiş:

# 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'

Hibrit Yaklaşım (Gerçek Dünyada En Yaygın)

Ç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"

Dikkate değer bir nokta: Farklı dokümantasyon türlerinin nerede yaşadığı konusunda net olmak gerçekten yardımcı olur. Birisi “RFC nerede?” diye sorduğunda ideal olarak açık bir cevap olmalı; birden çok sistem arasında hazine avı değil.

İşe Yarayan Bir Uygulama Yaklaşımı

Faz 1: Temel (1-2. Aylar)

1-2. Hafta: Altyapı Kurulumu

• Arama ile MkDocs deploy et
• RFC/ADR şablonları oluştur
• Otomatik doğrulama pipeline’ı kur
• Belge onay workflow’u belirle

3-4. Hafta: Şampiyon Eğitimi

• Dokümantasyon şampiyonları seç
• Şablonlar ve süreçler konusunda eğit
• Düzenli inceleme kadansı kur
• Feedback mekanizmaları oluştur

5-8. Hafta: Pilot Takım

• Pilot için 1-2 takım seç
• Kritik bilgiyi taşı
• İlk RFC incelemelerini yap
• Feedback topla ve iterate et

Faz 2: Benimseme (3-6. Aylar)

3. Ay: Zorunluluk ve Standartlar

• Mimari değişiklikler için RFC zorunlu tut
• Dokümantasyonsuz yeni servis olmasın
• Haftalık RFC inceleme toplantıları
• Kod incelemesinde dokümantasyon incelemesi

4-5. Ay: Bilgi Taşıma

• Mevcut kritik bilgiyi denetle
• Risk ve etkiye göre önceliklendir
• Yeni formata sistematik taşıma
• Eski dokümantasyon sistemlerini emekliye ayır

6. Ay: Kültür Entegrasyonu

• Performans değerlendirmelerinde dokümantasyon hedefleri
• İyi dokümantasyon için tanınma
• Planlamada dokümantasyon borcu
• Çapraz takım RFC katılımı

Faz 3: Optimizasyon (6-12. Aylar)

7-9. Ay: Otomasyon

• Sistem dokümantasyonunu otomatik üret
• Akıllı belge önerileri
• Kırık link tespiti ve düzeltmesi
• Arama analitikleri ve iyileştirme

10-12. Ay: Ölçeklendirme

• Tüm mühendislik organizasyonuna yaygınlaştır
• Gelişmiş analitikler ve metrikler
• Diğer sistemlerle entegrasyon (Slack, JIRA, vb.)
• Sürekli iyileştirme süreçleri

Değerini Kanıtlamış Dokümantasyon İlkeleri

Farklı takım bağlamlarında tekrar eden birkaç ilke, iyi dokümantasyon kararlarına rehberlik eder:

1. Zaman Yatırımı Olarak Dokümantasyon, Zaman Maliyeti Değil

Sağlam dokümantasyona harcanan zaman katları halinde geri döner. Birisi net bir ADR yazdığında, takımın takip eden aylarda aynı mimari tartışmayı birden çok kez yapması genellikle önlenir.

2. Tutarlılık Genellikle Yaratıcılığı Yener

Tutarlı şablonlar ve süreçler, herkesin kendi yaklaşımını bulmasına izin vermekten daha iyi ölçeklenir. Dokümanlar benzer desenleri takip ettiğinde, insanların farklı takımlar ve projeler arasında bilgi bulması çok daha kolaylaşır.

3. Bağlam Genellikle Uygulama Detaylarından Daha Önemli

Kod ne olduğunu gösterir, yorumlar nasıl olduğunu açıklar, ama karar dokümanları neden olduğunu yakalar. “Neden” genellikle refactoring, migrasyon ve yeniden yazma işlemlerinden kurtulan şeydir; daha sonra yeniden yapılandırılması en zor olan kurumsal hafıza budur.

4. Güncellenmiş Belgeler Mükemmel Belgeleri Yener

Düzenli olarak güncellenen makul bir belge, bayatlayan mükemmel bir belgeden daha değerlidir. İşleri güncel tutmayı kolaylaştıran süreçler kurmak, ilk seferde her şeyi doğru yapmaya çalışmaktan daha fazla değer üretir.

5. Yaratım Değil, Kullanıma Odaklan

Yazılan dokümanları saymak yerine sonuçlara bakmak daha yararlıdır: yeni takım üyeleri ne kadar hızlı verimli hale geliyor, insanlar yaygın sorulara cevap bulabiliyor mu, aynı kavramlar ne sıklıkta yeniden açıklanıyor. Amaç daha fazla içerik yaratmak değil, bilgiyi erişilebilir kılmaktır.

Sonraki Adımlarınız: Küçük Başlayın, Sistemli Düşünün

Her şeyi bir anda elden geçirmek gerekmez. Küçük ama görünür bir şeyle başlamak iyi çalışır:

Bu Hafta:

• Son zamanlarda karışıklık yaratan kritik bir sistem seçin
• Bir mimari kararı açıklayan basit 1 sayfalık ADR yazın
• Takım kanalınızda paylaşın ve feedback isteyin

Bu Ay:

• Takımınız için temel RFC şablonu oluşturun
• Basit dokümantasyon sitesi kurun (GitHub wiki bile işe yarar)
• Takım toplantınızda haftalık 30 dakikalık “dokümantasyon incelemesi” belirleyin

Bu Çeyrek:

• 2-3 dokümantasyon şampiyonu eğitin
• Tüm önemli değişiklikler için RFC zorunlu tutun
• Adaptasyon süresi ve çapraz takım sorularını ölçün
• Dokümantasyon ROI’nizi hesaplayın

Rekabet Avantajı Olarak Dokümantasyon

Dokümantasyon sadece bilgiyi korumakla ilgili değil; herhangi bir bireysel katkıcının ötesinde büyüyebilecek organizasyonel yetenekler inşa etmekle ilgili.

Rakipler özellikleri kopyalayabilir hatta kilit kişileri işe alabilir, ama kurumsal bilgi, karar bağlamı ve yeni takım üyelerini hızla hızlandırabilme yeteneği çoğaltılması çok daha zor olan şeylerdir.

İyi dokümantasyon, zamanla birleşen bir teknik kaldıraç biçimidir. Bir takımın bireysel katkıcı koleksiyonundan öğrenen organizasyona evrimine yardımcı olabilecek şeylerden biri.

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. Bu çeyrek içinde en çok karışıklığa yol açan kararı belgeleyen tek bir ADR ile başlamak, pratiğin takımınıza uygun olup olmadığını test etmek için yeterli.

Kaynaklar

• Diátaxis Çerçevesi - 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 - 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ı - 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ı - 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ü - Google SWE kitabından dokümantasyonun ölçekte kod gibi nasıl ele alındığına dair derinlemesine bölüm