1. Dokümantasyon Neden Sıkıcı Ama Hayati?
Dokümantasyon, “kimsenin okumadığı uzun sayfalar” olarak kurgulanırsa gerçekten sıkıcıdır. Ama iyi kurgulanmış bir teknik dokümantasyon envanteri, ekipte iki kritik riski azaltır:
- Bus-factor (tek kişiye bağımlılık)
- Yanlış müdahale (gece/krizde yanlış adım atma)
Dokümanlar aynı zamanda yeni ekip üyelerinin ramp-up süresini düşürür, ajans değişimlerinde bilgi transferini kolaylaştırır ve denetim/uyum süreçlerinde (özellikle güvenlik ve KVKK) “kanıt” üretir. Özellikle erişim notları, log referansları ve hassas operasyon adımları için dokümantasyon erişimi ve veri güvenliği yaklaşımı kritik hale gelir.
Sözlü kültürün gizli maliyeti
Sözlü kültür hızlı görünür; ama ölçeklenmez. “Şöyle yapıyorduk” cümlesi; ekip büyüdükçe, vardiya/on-call başladıkça ve entegrasyon sayısı arttıkça risk üretir. Otellerde PMS/OTA ve rezervasyon motoru gibi bileşenler; B2B’de API/portal ve ödeme akışları sözlü kültürle yönetilmeye çalışıldığında, incident anında müdahale süresi uzar.
☑ Mini Check
- •“Bu sistemi kim biliyor?” sorusuna tek isim mi çıkıyor?
- •Aynı incident tipi son 6 ayda tekrar etti mi?
- •Yeni bir ekip üyesi ilk deploy’u kaç günde yapabiliyor?
Ne yapmalıyım?
- • Dokümantasyonu “devamlı yazı” değil envanter + şablon olarak tasarla.
- • Runbook’ları “sık yaşanan 10 senaryo”dan başlat; sonra genişlet.
- • Her dokümana owner + last-updated + review cycle ekle.
2. Hangi Doküman Türleri Gerekli?
Dokümantasyon “tek doküman” değildir; farklı ihtiyaçlar için farklı türler gerekir. Buradaki amaç; yüzlerce sayfa üretmek değil, kritik bilgiyi doğru formatta tutmaktır. Özellikle uzaktan çalışan ekiplerde dağıtık ekiplerde bilgi devri yazılı süreç olmadan sürdürülebilir olmaz.
Minimum Doküman Seti (çekirdek paket)
- Teknik Mimari (Architecture Overview)
- Setup (Local + Dev/Staging/Prod)
- Deploy & Release (pipeline, rollback, checklist)
- Runbook (incident müdahale adımları)
- SSS / Operasyon Notları (FAQ, sık sorular, contact/escalation)
Opsiyonel ama çok değerli dokümanlar
- •Entegrasyon Kataloğu: PMS/OTA, CRM, ödeme, analytics, CDN, WAF
- •Data/Tracking Sözlüğü: event adları, dönüşüm tanımları, dashboard kaynakları
- •Güvenlik Runbook’ları: WAF/DDoS, credential rotasyonu, log inceleme
- •KVKK/İhlal Runbook’u: incident & breach süreçleri (hukuki/operasyonel koordinasyon)
İç link önerisi
- •Sunucu ve erişim güvenliği notları ayrıca tutulmalı
- •KVKK ve veri işleme sorumlulukları ilgili operasyon adımlarına bağlanmalı
- •Erişim logları ve veri güvenliği kayıtları doküman envanterinde tanımlanmalı
- •Bakım ve destek çalışma modeli bu doküman setiyle birlikte okunmalı
Dokümanları “nerede” tutmalı?
Araç seçimi (Confluence/Notion/Git repo/wiki) ikinci planda; kritik olan:
- •Arama yapılabilirlik
- •Versiyonlama
- •Erişim yetkisi (kim okuyabilir/yazabilir)
- •Runbook’ların on-call sırasında “tek tıkla” bulunabilmesi
☑ Mini Check
- •Mimari dokümanı, “sistem haritası + kritik bağımlılıklar” içeriyor mu?
- •Deploy dokümanı rollback’i net söylüyor mu?
- •Entegrasyon kataloğu token/endpoint sahipliği içeriyor mu?
Ne yapmalıyım?
- • Doküman türlerini listele ve “olması gereken minimum set”i kilitle.
- • Her tür için kısa şablon oluştur; herkes aynı formatta yazsın.
- • Dokümanları tek “Docs Home” altında envanterle yönet.
3. Runbook Nedir? Dokümantasyondan Farkı Nedir?
Dokümantasyon “nasıl çalışır?”ı anlatır; runbook “şu anda ne yapmalıyım?”ı söyler. Runbook, özellikle incident anında, karar yükünü azaltan operasyonel rehberdir.
Runbook’un 3 altın kuralı
- Amaç: Bu runbook neyi çözer? (1–2 cümle)
- Adımlar: Sıralı ve ölçülebilir (komut/ekran yolu/URL)
- Doğrulama: “Düzeldi”yi nasıl anlarız? (KPI/log/healthcheck)
Soru : Runbook nedir, dokümantasyondan farkı nedir?
Cevap: Runbook, incident anında adım adım yapılacak işlemleri ve doğrulama kriterlerini içeren operasyon rehberidir. Dokümantasyon sistemi anlatır; runbook ise “şimdi hangi adımı atacağım?” sorusunu yanıtlar.
“İyi runbook” nasıl görünür?
- •2 dakikada taranabilir
- •Kritik uyarılar (⚠️) net
- •Eskalasyon/iletişim bilgisi içerir
- •“Geri alma” adımı varsa açık yazar
- •En sonda kısa bir Mini Check verir
☑ Mini Check
- •Runbook başında “etki” ve “kapsam” yazıyor mu?
- •Adımlar “tık tık” ilerliyor mu yoksa yorum mu istiyor?
- •Doğrulama metrikleri var mı?
Ne yapmalıyım?
- • Runbook’ları “amaç→adımlar→doğrulama” formatına zorla.
- • Her runbook’a “son güncelleme” ve “owner” ekle.
- • On-call eğitiminde 3–5 runbook “dry-run” yaptır.
4. On-Call ve Incident Runbook’ları
On-call yapısı yoksa bile, “mesai dışı incident” gerçeği vardır. Otellerde yüksek sezon; B2B’de SLA’li müşteri beklentisi bu ihtiyacı büyütür. Bu noktada on-call playbook ile incident sonrası runbook güncellemesi birlikte düşünülmelidir; runbook’ların bir bölümü de “sık incident” senaryolarını kapsamalıdır.
Sık incident senaryoları (başlangıç listesi)
- •Cache temizleme / CDN purge (yanlış cache, eski kampanya)
- •Servis restart / container recycle (geçici kilitlenme)
- •DNS değişimi / SSL sertifika yenileme
- •Rate limit / bot trafiği / WAF kuralı (ani trafik)
- •Form/rezervasyon akışı bozulması (critical funnel)
- •Entegrasyon time-out (PMS/OTA, ödeme, CRM)
Otel için örnek runbook seti
- •PMS/OTA bağlantı kontrolü (availability/fiyat akışı)
- •Rezervasyon motoru yönlendirme doğrulama (UTM/cross-domain)
- •Kampanya sayfası “fiyat/paket” güncellik testi
- •Panel (CMS) erişim/rol sorunları
B2B için örnek runbook seti
- •API healthcheck (latency/error rate)
- •Portal login/auth sorun giderme
- •CRM entegrasyon mapping kontrolü
- •Ödeme/checkout hata triage
Key Statistics / Data Point (yumuşatılmış): İyi runbook’ları olan ekiplerde, gece incident’lerine müdahale süresi ve yeni ekip üyesinin ramp-up süresi genelde anlamlı ölçüde azalır.
☑ Mini Check
- •Incident türleri “top 10” listelenmiş mi?
- •Her incident türü için 1 runbook var mı?
- •Eskalasyon: kime ne zaman haber veriliyor?
Ne yapmalıyım?
- • Önce “en sık/ en riskli 10 incident”i seç; runbook’ları onlardan başlat.
- • On-call için “war-room” kanalı ve iletişim şablonu belirle.
- • Güvenlik senaryolarını ayrıca runbook’laştır (sunucu güvenlik + KVKK).
5. Doküman Versiyonlama, Sahiplik ve “Güncel Kalma” Problemi
Doküman yazmak kolay; güncel tutmak zordur. Bu yüzden dokümantasyonun “eski bilgi çöplüğü”ne dönüşmesini engelleyecek sistem gerekir.
Sahiplik (Owner) ve last-updated alanları zorunlu olmalı
Her dokümanda şu 3 alanı en üstte standartlaştırın:
- •Owner (sorumlu kişi/rol)
- •Last updated (tarih)
- •Review cycle (90/180/365 gün)
Periyodik review nasıl işler?
- •90 gün: runbook’lar ve değişken operasyon adımları
- •180 gün: setup/deploy dokümanları
- •365 gün: mimari overview (büyük değişiklik yoksa)
Bu blog satırına göre Refresh Cycle: 365.
Varsayım: Runbook’lar için 90–180 gün daha sık review önerilir; mimari en az yılda 1 kez.
Doküman güncelleme tetikleyicileri (event-based)
- •Büyük release/major refactor sonrası
- •Incident/postmortem sonrası (yeni öğrenim)
- •Entegrasyon değişikliği (PMS/OTA, ödeme, CRM)
- •Güvenlik olayı / KVKK süreci güncellemesi
☑ Mini Check
- •Dokümanlarda owner ve last-updated var mı?
- •Review takvimi takıma işlendi mi?
- •Postmortem sonrası runbook güncelleniyor mu?
Ne yapmalıyım?
- • Docs Home’da “review due” listele (yaklaşan dokümanlar).
- • Her major değişiklikte “docs update” görevini Done kriterine ekle.
- • Runbook’ları incident sonrası güncellemeden kapatma.
6. Dokümantasyon Envanteri & Runbook Şablonu İndir
Dokümantasyon Envanteri & Runbook Şablonu İndir — Yazılım / Bilgi Yönetimi (v1.0)
Bu şablon; web projelerinde bilgi kaybını azaltmak için doküman türlerini envanter halinde toplar, her dokümana owner/last-updated/review alanlarını ekler ve incident runbook’ları için standart sayfa yapısı sunar. Hedef, on-call ekiplerin ve bakım süreçlerinin kişilerden bağımsız işlemesidir. Otel (PMS/OTA/rezervasyon) ve B2B (API/portal) senaryolarına uyarlanabilir.
Kim Kullanır?
Ajans PM + teknik lider + otel/B2B operasyon sorumlusu.
Nasıl Kullanılır?
- Envanter tablosunu doldurup eksik dokümanları önceliklendir.
- En sık 5–10 incident için runbook şablonunu kullanarak sayfaları oluştur.
- Review takvimini işlet; her major değişiklik veya postmortem sonrası güncelle.
Ölçüm & Önceliklendirme (Kısa sürüm)
- ▢ ✅ Envanterde owner/last-updated dolu
- ▢ ✅ İlk 10 incident için runbook var
- ▢ ✅ Review takvimi takıma işlendi
- ▢ ✅ Güvenlik/KVKK runbook’ları ilgili sayfalara bağlandı
PDF içinde: Problem→Kök Neden→Çözüm tablosu + 14 gün sprint planı + önce/sonra KPI tablosu
5) Kontrol listesi
- •Envanterde owner/last-updated dolu
- •İlk 10 incident için runbook var
- •Review takvimi takıma işlendi
- •Güvenlik/KVKK runbook’ları ilgili sayfalara bağlandı
Deliverables
- •Envanter tablosu
- •Runbook Hub
- •10 incident runbook’u
- •review takvimi
7. Otel ve B2B İçin Örnek Doküman Setleri
Aynı şablon setini iki farklı dünyaya uyarlamak gerekir. Otelde sezon ve çoklu entegrasyon baskısı; B2B’de ürünleşmiş süreç ve müşteri SLA beklentisi ağır basar. Özellikle PMS OTA operasyon runbook’u ile çağrı merkezi destek bilgi tabanı gibi operasyon kaynakları, otel tarafında bilginin doğru ekibe doğru anda ulaşmasını sağlar.
Otel doküman seti (örnek)
- •Mimari: web + CMS + rezervasyon motoru + PMS/OTA + call center akışı
- •Setup/Deploy: staging/prod, kampanya yayın akışı, cache/CDN kuralları
- •Runbook: “rezervasyon akmıyor”, “fiyat gelmiyor”, “kampanya yanlış görünüyor”
- •Güvenlik runbook: WAF/DDoS, erişim rolleri, log erişimi
- •KVKK/ihlal runbook: olay bildirimi, kayıt/kanıt toplama, iletişim
B2B doküman seti (örnek)
- •Mimari: portal + API + auth + ödeme + veri/raporlama
- •Setup: env, secrets, deploy pipeline, feature flag
- •Runbook: “login bozuldu”, “API latency arttı”, “CRM entegrasyonu düştü”
- •Operasyon: SLA, ticket lifecycle, escalation matrisleri
| Doküman Türü | Örnek İçerik | Owner | Last Updated | Review Cycle | Lokasyon |
|---|---|---|---|---|---|
| Mimari Overview | Sistem haritası + bağımlılıklar | Tech Lead | TBD | 365 | Docs Home |
| Setup | local/staging/prod adımları | DevOps/Dev | TBD | 180 | Repo/Wiki |
| Deploy & Rollback | release checklist + rollback | Release Owner | TBD | 180 | Runbook Hub |
| Runbook (Incident) | cache purge, restart, DNS | On-Call Owner | TBD | 90 | Runbook Hub |
| KVKK/İhlal Runbook | breach triage + kayıt | DPO/Legal+IT | TBD | 180 | Compliance |
☑ Mini Check
- •Envanterde “boş” alan kalmadı mı (owner/tarih)?
- •Otel için PMS/OTA ve rezervasyon runbook’ları var mı?
- •B2B için API/portal runbook’ları var mı?
Ne yapmalıyım?
- • Envanteri çıkar, sonra eksik dokümanları sırala (en riskli önce).
- • Otel/B2B için ayrı “runbook paketleri” oluştur.
- • Uyum ve güvenlik runbook’larını ilgili sayfalarla bağla.
8. Fark Yaratan Katman: “Bilgi Yönetimi Modeli” ile Bus-Factor’ı Düşürmek
TR’de runbook kavramı az biliniyor; çoğu ekipte kritik adımlar hâlâ “sözlü kültür”le taşınıyor. Bu rehberin farkı; dokümantasyonu “nice to have” değil, incident-ready ops sistemi olarak ele almasıdır. Süreci sistematik kurmak için Bakım ve Destek hizmetiyle bilgi kaybını önleme sürecinizi güçlendirin ve uygulama detayları için Bakım ve Destek hakkında sık sorulan sorular sayfasına geçin.
Basit model: 4 katman
- Docs Inventory (envanter)
- Runbook Hub (operasyon rehberleri)
- On-call + Ticketing entegrasyonu
- Review & versioning (süreç hafızası)
☑ Mini Check
- •Runbook’lar “en çok yaşanan 10 olay”ı kapsıyor mu?
- •Her dokümanın sahibi var mı?
- •Review periyodu işletiliyor mu?
Ne yapmalıyım?
- • İlk hafta: envanter + 3 runbook (cache, restart, DNS)
- • İlk ay: otel/B2B kritik akış runbook’ları + review ritmi
- • İlk çeyrek: ticketing/SLA ile bağla; postmortem’den runbook’a döngü kur
Bir Sonraki Adım
Bilgi kaybı riski yüksek otel, ajans ve B2B ekiplerinde on-call ve bakım süreçlerini kişiden bağımsızlaştırmak için.
Sık Sorulan Sorular
Runbook nedir, dokümantasyondan farkı nedir?▾
Hangi doküman türlerine ihtiyacım var?▾
Otel ve B2B projeleri için runbook örnekleri neler?▾
Dokümantasyonun güncel kalmasını nasıl sağlarız?▾
Sistemi sadece bir kişi biliyor, bu riski nasıl azaltırım?▾
Runbook yazarken en sık hata nedir?▾
Dokümanları nerede tutmalıyım?▾
İlgili İçerikler