Yazılım dokümantasyonu hakkında konuşurken herkesin dediği: “önemli”. Ama uygulamada dokümantasyon sürekli geriye düşen, stale olan, kimsenin güncellemediği bir alan.
10 farklı ekip ve proje boyunca dokümantasyon yaklaşımlarını denedim. Bazıları işe yaramadı, bazıları oturdu. Bu yazıda işe yarayanları aktarıyorum.
Dokümantasyonun 4 türü
Her dokümantasyon aynı değil. Farklı amaç, farklı audience, farklı format:
1. Onboarding dokümantasyonu (README, setup guide). Yeni developer için. “Nereden başlıyorum?”
2. Reference dokümantasyon (API docs, config reference). Geliştirirken “Bu fonksiyon ne döndürüyor?” sorusunun cevabı.
3. Explanation (architecture, design docs, ADR). “Niçin bu şekilde?” sorusunun cevabı.
4. How-to / Runbook. “Bu görevi nasıl yaparım?” “Bu incident’ta ne yaparım?”
Bunların hepsini tek “documentation” şemsiyesinde karıştırmak yazım ve bakımı zorlaştırıyor. Her biri ayrı place, ayrı format, ayrı cadence.
README: projenin kapısı
README en çok okunan dokümantasyon. Olması gerekenler:
One-line description: ne bu proje?
Quick start: 5 komutla çalıştır.
Prerequisites: Node >= 18, Docker, vs.
Contributing guide link: eğer kontribütörler varsa.
Links: detaylı docs nerede, API reference, changelog.
README gereğinden uzunsa kimse okumuyor. 200 satır üst sınır. Detail başka dosyalara taşımalı.
Architecture doc: big picture
Yeni mühendisin “büyük resim”i anlaması için. Ben genelde şu template’i kullanıyorum:
# Architecture
## Overview
[2-3 paragraf: bu sistem ne yapıyor, ana prensipler nedir]
## System Diagram
[Mermaid veya excalidraw diagram]
## Services
### API Gateway
- Purpose: public traffic entry
- Tech: NGINX + custom Lua
- Dependencies: auth service, rate limiter
### User Service
- Purpose: auth, user CRUD
- Tech: Go + PostgreSQL
- Dependencies: session store
...
## Data Flow
[Critical user journey'lerin diagram'ı: signup, login, order creation]
## Key Design Decisions
- Why PostgreSQL over MongoDB: ACID requirements, complex joins
- Why message queue: async processing, retry guarantees
- ...Yarım saatte okunabilir, big picture veriyor. Detay başka yerde.
ADR: Architecture Decision Records
Neden bu karar alındı? 6 ay sonra “niye bu framework?” diye sorulan soru için.
ADR format:
# ADR-0012: PostgreSQL seçimi
## Status
Accepted
## Context
Sistem CRUD-heavy, günde 10K sipariş, reporting için complex join'ler gerekli.
## Decision
PostgreSQL kullanıyoruz, MySQL veya MongoDB yerine.
## Consequences
- Advanced window functions, CTE'ler mevcut (pozitif)
- Türkiye hosting seçenekleri MySQL kadar bol değil (negatif)
- Team Postgres bilgisi ortalama seviyede (risk: öğrenme)Her önemli teknoloji/pattern kararı bir ADR. Repository’de /docs/adr/ altında numbered.
ADR’nin değeri zaman içinde çıkıyor. 2 yıl sonra “niye bunu yaptık” sorusu olduğunda cevabı var.
Runbook: operational scenarios
System çalışıyor, birisi on-call’da. “Hangi butonu çevirmem gerek?” sorusunun cevabı runbook’ta.
Her alarm için bir runbook:
# Alert: High API Error Rate
## Context
`api_error_rate > 5%` alarm'ı tetiklendiğinde.
## Impact
Kullanıcılar checkout'ta fail oluyor olabilir. Revenue impact.
## Investigation
1. Grafana'da hangi endpoint etkileniyor bak: https://grafana/...
2. Recent deploy var mı kontrol et: `kubectl rollout history`
3. Upstream service down mu? Stripe status page, payment provider status.
## Mitigation
- Recent deploy sonrası artmışsa: rollback `kubectl rollout undo`
- Upstream down: circuit breaker aktif mi kontrol et, feature flag ile disable et
- DB connection pool dolu: scale up worker
## Postmortem
Incident resolved olduktan sonra postmortem wiki'sine yaz.Runbook alarm’ın kendisine direct link ile bağlı. On-call engineer alarm tıklayınca runbook açılıyor.
Runbook’u yazmak = aksiyon planını maddeler halinde somutlaştırmak. Kriz anında “ne yapıyordum ben?” sorusunu soracak değilsiniz.
Kim yazar?
Klasik hata: “technical writer işe alacağız, dokümantasyonu onlar yazar”. Sonuç: yazıldı ama stale, detail eksik.
İyi pattern: kodun sahibi docs’un sahibi. Feature yazan PR’da docs update olmalı. Docs-as-code.
CI’da enforcement:
– PR feature ise docs update zorunlu (reviewer checkpoint)
– README referred ediyor ama file yok = CI fail
– Broken link = CI fail
Automated check’ler bakımsızlığı önlüyor.
Docs-as-code: repo’da tutun
Confluence, Notion gibi external tool’lara dokümantasyonu koymak siloluyor. Repo’dan ayrı, version kontrolde değil, PR review’dan geçmiyor.
Ben /docs/ klasörünü repo’da tutmayı öneriyorum. Markdown format. Git history = docs history. Change’ler PR’da review ediliyor.
Ekstra: docs’u MkDocs, Docusaurus, Nextra gibi SSG ile statik site haline getirip CI’da deploy. Team kendi site’ında okuyor.
Her PR’da docs review
PR review checklist’e şunu eklemek:
- Yeni feature dokümante edildi mi?
- Changed behavior doc’u güncelledi mi?
- Breaking change varsa migration guide var mı?
“Small fix, docs update gerekmez” demeyin. Dokümantasyon eksik kalması genelde burada başlıyor.
Stale docs: döner hedef
Dokümantasyon bir kere yazılıp bitmiyor. Code değişiyor, docs güncelleniyor. Disiplin olmayan ekipte 6 ay sonra docs stale.
Anti-pattern: “canlı” doc’un altına “not: bu info 2024’ten kalma, güncel değil olabilir” yazma. Doc yanlış ise update et, disclaimer koyma.
İyi pattern: docs maintenance sprintlik iş. Her sprint’te belirli docs page’i review edip güncelleme.
Büyük ekiplerde “doc gardener” rotation: her ay bir kişi 4 saatini docs review’a ayırıyor, stale page’leri düzeltiyor.
Yaygın hata: yazım fobisi
“Yazma’ya yeterince iyi değilim” diyen developer’lar var. Dokümantasyon mükemmel İngilizce veya edebi Türkçe gerektirmiyor.
Kısa cümleler, net bilgi yeterli. “Bu fonksiyon X yapıyor. Y return ediyor. Hatada Z exception atar.” Bu yeterli doc.
Docs writing kas hafızası. Her feature’a doc yaz, 3 ay sonra hızlı yazıyorsun.
Yaygın hata 2: örnek eksikliği
Açıklama olmadan örnek, örnek olmadan açıklama – ikisi de eksik. İyi doc ikisini birleştirir.
### createOrder(data)
Yeni bir order oluşturuyor.
**Parameters:**
- `data.userId` (string): user ID
- `data.items` (array): order items
- `data.totalCents` (integer): toplam kuruş
**Returns:** Order object
**Example:**javascript
const order = await createOrder({
userId: ‘user_123’,
items: [{productId: ‘p1’, quantity: 2}],
totalCents: 15000
});
// order.id, order.status, …
**Throws:**
- `InsufficientStockError`: item stock yetersizse
- `PaymentRequiredError`: user payment method eksikseReferans doc’ları için bu pattern.
Documentation-first development
Bazen feature geliştirmeden önce doc yazmak. “Bu API endpoint şunları yapacak, şu parametre alacak” yazıp önce team’den feedback al, sonra implement.
Bu pattern API tasarımını önden düşündürüyor. Developer “ilginç, doc’ta nasıl görünecek?” sorusuna baktığında API’nin ergonomik olup olmadığını erken görüyor.
Metric: docs ne kadar iyi
Dokümantasyon kalitesini ölçmek zor ama proxy metric’ler:
- Onboarding time (yeni developer productive olma süresi)
- Self-serve vs Slack help ratio (kullanıcı sorusu docs’tan cevaplanabiliyor mu)
- Doc PR frequency (aktif mi?)
- Broken link count (maintenance seviyesi)
Quarterly review: docs ne kadar current?
Son tavsiye
Dokümantasyon hobisi değil, engineering practice. Yazmamak technical debt.
6 maddelik minimum:
1. README her repo’da var
2. Architecture doc sistem için
3. ADR önemli kararlar için
4. Runbook alarm’lar için
5. PR review’da docs check
6. Quarterly doc maintenance sprint
Bu 6 madde uygulanan ekipte onboarding hızlı, incident response hızlı, bilgi silosu minimal. Dokümantasyon olmadan büyüyen ekip her bir sorunla tek başına boğuşmak zorunda kalıyor.