Dokümantasyon

15-11 hattı şu ilkeyle uğurladı: bakımı yapılabilir sistem, davranışı ve kararları yazılı olan sistemdir. Bu ders o cümlenin araçlarını verir — ve önceki hatlardan biriken en uzun senet zincirini öder: 13-01'in "hangi kimlik yöntemi, neden" kararı, 14-02'nin artık risk kabulü, 14-09'un güvenli geliştirme kararları, 14-11'in denetçiye gösterilecek kanıtı ve 15-11'in teknik borç kaydı, hepsi tek bir biçime akar: ADR. Yanında README'nin beş dakika kuralı, API dokümanının "örneksiz doküman yoktur" ilkesi, 15-11 ve 2. dersin Keep a Changelog ↔ Conventional Commits otomasyonu, 14-10 ve 15-09'un gece üçteki nöbetçi için runbook'u, C4 diyagramları ve teknik yazımın ilkeleri. Ortak kural tektir: doküman kodla aynı depoda yaşar, aynı PR'da güncellenir; aksi hâlde birkaç ayda yalan söylemeye başlar.

01Ne öğreneceksin

02Ne kadar doküman, kim için

Manifestonun "kapsamlı dokümantasyondan çok çalışan yazılım" değeri (10. ders) sık yanlış okunur: "doküman yazma" demez, "yeterli olanı yaz" der. Yeterlilik okuyucuyla tanımlanır; bir sistemin en az beş okuyucusu vardır ve her biri farklı şey arar: yeni gelen geliştirici (nasıl kurarım, nereden başlarım), bakımcı (bu neden böyle), işletmeci/nöbetçi (alarm çaldı, ne yapayım), tüketici (API'yi nasıl çağırırım), karar verici/denetçi (hangi risk kabul edildi, kim onayladı). Tek bir "doküman" hepsine hitap edemez; iyi bir düzen türleri ayırır. Yerleşik çerçeve (Diátaxis) dört tür sayar:

Docs-as-code bu dersin işletim kuralıdır: doküman Markdown olarak kodla aynı depoda (docs/, README.md, CHANGELOG.md), aynı PR'da değişir, aynı incelemeden geçer (8. ders), CI bozuk bağlantıyı yakalar, sürümle birlikte tag'lenir. Wiki'nin sorunu bu değildir: wiki koddan ayrı yaşar, PR onu güncellemeye zorlamaz, altı ayda bayatlar. Bayat doküman, olmayan dokümandan kötüdür — okuyucu ona güvenip yanlış yapar. Bundan dokümantasyon borcu kavramı doğar (15-11'in borç kadranının bir bölgesi): bilerek yazılmayan doküman kayda geçer ve faiz işler — her yeni gelen aynı soruları sorar, her nöbetçi aynı komutu yeniden keşfeder.

03README: beş dakika kuralı

README, depoyu açan herkesin ilk okuduğu ve çoğu zaman tek okuduğu dosyadır. Ölçütü tektir: hiç görmemiş biri beş dakikada kurup çalıştırıp testleri koşturabilmeli. Bunu sağlayan iskelet:

# Başvuru API

Sınav başvurularını alan ve doğrulayan ASP.NET Core servisi.

## Gereksinimler
- .NET 8 SDK · Docker (PostgreSQL için) · `dotnet ef` aracı

## Kurulum ve çalıştırma
```bash
git clone https://git.kurum.gov.tr/basvuru/api.git && cd api
docker compose up -d db
dotnet ef database update --project src/Basvuru.Api
dotnet run --project src/Basvuru.Api        # https://localhost:5001/swagger
```

## Yapılandırma
| Değişken | Zorunlu | Varsayılan | Açıklama |
|---|---|---|---|
| `ConnectionStrings__Basvuru` | evet | — | PostgreSQL bağlantı dizesi (sır: kasadan, 13-10) |
| `Basvuru__SonGun` | hayır | `23:59` | Son başvuru saati |

## Test
`dotnet test` — entegrasyon testleri Docker ister (Testcontainers).

## Dağıtım · Katkı · Lisans
Bkz. `docs/runbook.md` · `CONTRIBUTING.md` · MIT

Sıra bilinçlidir: ne (bir cümle), gereksinimler, kopyalanabilir kurulum komutları, yapılandırma tablosu, test, sonra gerisi bağlantıyla. README büyüdükçe docs/'a dallanır; README özet ve giriş kapısı kalır. Kökteki komşu dosyalar da sözleşmedir: CONTRIBUTING.md (dal adı kalıbı, commit biçimi, PR şablonu — 7. ve 8. dersin kararları burada yazılıdır), LICENSE, SECURITY.md (zafiyet nasıl bildirilir — 14-09), CODEOWNERS.

Markdown, sıfırdan: düz metin dosyasının birkaç işaretle biçimlenmesi. # başlık (sayısı seviye), boş satır paragraf, - madde, 1. numaralı madde, **kalın**, `kod`, üç ters tırnak arasında kod bloğu (dilin adı vurgulama için: ```bash), [metin](adres) bağlantı, | ile tablo, > alıntı. Platformlar (GitHub, GitLab, Azure DevOps) README'yi otomatik gösterir ve çoğu Mermaid diyagram bloklarını çizer (08. bölüm). Bu kadarı yeter; Markdown'ın değeri sadeliğinde — diff'te okunur, PR'da incelenir, herhangi bir editörle yazılır.

04ADR: mimari karar kaydı

Bir sistemin en çabuk kaybolan bilgisi nedendir. Kod "ne"yi gösterir, commit "ne değişti"yi; "neden PostgreSQL, neden JWT değil cookie, neden mikroservis değil modüler monolit" sorusunun cevabı bir yıl sonra ekipten ayrılmış birinin aklındadır. Architecture Decision Record (Nygard, 2011) bunu kısa, numaralı, değişmez bir belgeye bağlar:

# ADR-0007: Kimlik doğrulama için kurum OIDC sağlayıcısı

Durum: Kabul edildi (2026-09-03) · ADR-0003'ü geçersiz kılar
Karar verenler: Backend ekibi, güvenlik ekibi

## Bağlam
Başvuru API'si kurum personeli ve dış adaylara hizmet verecek. Parola yönetimi
(saklama, sıfırlama, MFA) kurumun mevcut OIDC sağlayıcısında zaten var (13-07).
Mevzuat gereği kimlik verisi kurum dışına çıkamaz (14-13). Ekipte 8 kişi, MFA
altyapısı kurma kapasitesi yok.

## Değerlendirilen seçenekler
1. ASP.NET Core Identity ile kendi parola yönetimimiz
2. Kurum OIDC sağlayıcısı (Authorization Code + PKCE)
3. Dış SaaS kimlik servisi — mevzuat nedeniyle elendi

## Karar
Seçenek 2. API yalnız JWT doğrular; oturum ve MFA sağlayıcıda.

## Sonuçlar
+ Parola saklamıyoruz; MFA ve sıfırlama bedava; tek oturum açma.
− Sağlayıcı kesintisi = giriş yok; artık risk: kabul edildi (risk sahibi: BT Md.,
  14-02 kaydı R-12). Token ömrü 15 dk + refresh — 13-05 kararı.
− Yerel geliştirme için sahte sağlayıcı gerekir → teknik borç kaydı TB-4 (15-11).

Anatomi: bağlam (karar anındaki gerçekler ve kısıtlar — bunlar değişirse karar da gözden geçirilir), seçenekler (neyin reddedildiği en az neyin seçildiği kadar değerlidir), karar (tek cümle), sonuçlar (artıları ve eksileri, kabul edilen risk, doğan borç). Üç kural: (1) numaralı ve sıralı — docs/adr/0007-…md; (2) değişmez — karar değişirse eski ADR düzenlenmez, yeni ADR yazılır ve eskisinin durumu "geçersiz kılındı (bkz. 0012)" olur; böylece kararların tarihi okunur; (3) kısa — bir-iki sayfa; uzun tasarım dokümanı ayrı, ADR ona bağlantı verir.

Senet zinciri burada ödenir ve ADR'nin "sonuçlar" bölümü onu taşır: 13-01'in "güvenlik kararı gerekçesiyle kaydedilir" ilkesi → ADR'nin kendisi; 14-02'nin artık risk kabulü (risk sahibi adıyla) → sonuçlar bölümünün eksi satırı; 14-09'un güvenli geliştirme kararları (hangi kütüphane, hangi kripto) → ADR konusu; 14-11'in denetçiye kanıt ihtiyacı → "bu karar ne zaman, kim, neden" sorusunun tek dosyada cevabı; 15-11'in teknik borç kaydı → bilinçli alınan borcun doğduğu yer. Ne zaman yazılır: geri dönüşü pahalı (veritabanı, kimlik mimarisi, mesajlaşma altyapısı, dil/çerçeve), ekibi bağlayan (kodlama standardı, dal stratejisi — 7. dersin kararı bir ADR'dir, 9. dersin model seçimi de), ya da altı ay sonra "neden" diye sorulacak her karar. "Değişken adına ne koyduk" ADR değildir. ADR, PR'ın parçasıdır: kararı uygulayan PR, ADR dosyasını da getirir ve inceleme kararı da tartışır.

05API dokümanı: referans yetmez

6. hat OpenAPI'yi verdi (api-openapi): koddan üretilen, her ucu, parametreyi ve şemayı listeleyen referans. Referans, dört türden yalnız biridir; tüketicinin ilk sorusu "ilk çağrımı nasıl yaparım"dır ve OpenAPI buna cevap vermez. Tam bir API dokümanı:

• Başlangıç kılavuzu (öğretici): kimlik nasıl alınır (13. hat: hangi akış, token nereye konur), ilk istek, ilk yanıt — kopyalanabilir curl ile, beş dakikada.
• Her uç için örnek istek ve yanıt — gerçekçi veriyle. Kural: örneği olmayan uç dokümante edilmemiştir. OpenAPI şemasına example alanları eklenir; Swagger UI bunları gösterir.
• Hata tablosu: api-hata'nın Problem Details biçimi; hangi durum kodu ne zaman, type değerleri, tüketicinin ne yapması gerektiği (yeniden dene / düzelt / destek).
• Sürüm ve deprecation politikası (api-versiyon + 15-11): destek penceresi, kaldırma duyurusu süresi, Deprecation/Sunset başlıkları.
• Sınırlar: hız limiti, sayfalama, boyut; changelog (06. bölüm) — "2.0'a geçersem ne kırılır".

Bu, iç API için de geçerlidir: tüketici başka bir ekipse doküman, iki ekibin sözleşmesidir (19. hat). Kaynağı tek tutmak için açıklama ve örnekler OpenAPI belgesine yazılır (ASP.NET Core'da genel API üyelerinin XML belge açıklamaları Swashbuckle ile belgeye akar; bu, ekip içi "kod yorumu" tartışmasından ayrı bir konudur — dışa açılan sözleşmenin metnidir), Markdown kılavuz onu çevreler; ikisi aynı PR'da değişir.

06Changelog: geçmişten otomatik üretmek

15-11'in cümlesi: commit geçmişi geliştirici içindir, changelog tüketici için. Keep a Changelog biçimi:

# Changelog
Bu dosya Keep a Changelog 1.1 düzenine, sürümler SemVer'e uyar.

## [Unreleased]
### Added
- Engelli adaylar için ek süre alanı (BAS-233)

## [1.4.1] - 2026-09-01
### Fixed
- Son gün 23:59 başvuruları artık reddedilmiyor (BAS-201)
### Security
- Npgsql 8.0.5'e güncellendi (CVE-2024-32655)

## [1.4.0] - 2026-08-20
### Added
- Başvuru durumu sorgulama ucu `GET /basvurular/{id}/durum`
### Deprecated
- `GET /basvuru-durum?id=` — 2.0'da kaldırılacak; `Sunset` başlığı eklendi

Kurallar: en yeni üstte; her sürüm tarihli; altı bölüm (Added, Changed, Deprecated, Removed, Fixed, Security); Unreleased bölümü biriktirir ve sürümde adlandırılır; her satır iş kaydına bağlanır. Elle yazmak unutulur; 2. dersin Conventional Commits disiplini bunu otomatikleştirir — senedin ikinci yarısı:

Araç zinciri (18. hatta CI adımı olur): son tag'den (4. ders) bu yana commit'leri okur, sürüm numarasını hesaplar, CHANGELOG.md'yi üretir, annotated tag atar, platformda "Release" notu açar — semantic-release, release-please, .NET dünyasında GitVersion/Nerdbank.GitVersioning sürüm hesabı için. Kıdem notu: otomatik üretilen changelog taslaktır; yayın öncesi bir insan tüketici gözüyle okur, "refactor internal helper" gibi satırları atar, kırıcı değişikliğe geçiş yönergesi ekler. Otomasyon unutmayı önler, iletişimi insan yapar. Tag ↔ changelog ↔ Release notu üçlüsü aynı sürüm numarasını taşımalı; 7. dersin sürüm akışında "tag" adımı changelog'un mühürlendiği andır.

07Runbook: gece üçteki nöbetçi için

14-10 olay yönetimini, 15-09 üretimde "debugger değil kanıt" zincirini verdi; ikisi de aynı okuyucuyu varsayar: sistemi yazmamış, uykusuz, alarm ekranına bakan nöbetçi. Runbook (işletim el kitabı) ona yazılır ve ölçütü README'ninkine benzer: sistemi tanımayan biri alarmdan kurtarmaya beş dakikada geçebilmeli. İçeriği:

• Servis özeti: ne yapar, kimler kullanır, iş saatleri/kritikliği, sahip ekip ve eskalasyon (kim, hangi kanaldan, hangi sırayla).
• Bağımlılıklar: veritabanı, kimlik sağlayıcı, kuyruk, dış servisler — her biri için "çökerse ne olur".
• Nereye bakılır: sağlık ucu, dashboard bağlantıları, log sorguları (14-10'un korelasyon kimliğiyle), metrik adları. Kopyalanabilir sorgu ve komutlar.
• Alarm → adım: her tanımlı alarm için belirti, ilk kontrol, olası nedenler, müdahale, ne zaman eskalasyon. Bu bölüm kılavuz türündedir (02. bölüm): görev odaklı, numaralı, tek yol.
• Prosedürler: yeniden başlatma, geri alma (7. dersin sürüm akışının tersi; 18. hat), bakım moduna alma, veritabanı yedeğinden dönüş, sır döndürme (13-10).
• Bilinen sorunlar ve geçici çözümler; son olayların postmortem bağlantıları.

## Alarm: basvuru_api_5xx_orani > %2 (5 dk)
1. Sağlık: `curl -s https://basvuru.kurum.gov.tr/health` → "db": "Unhealthy" ise → adım 4
2. Log: son 15 dk, seviye Error, gruplandır: exception türü
   `kql: AppTraces | where SeverityLevel >= 3 | summarize count() by ExceptionType`
3. Son dağıtım 1 saat içindeyse → geri al: bkz. "Geri alma"; sonra eskalasyon: backend nöbetçi
4. DB bağlantı havuzu dolmuş olabilir: `SELECT count(*) FROM pg_stat_activity` > 90 →
   bağlantı sızıntısı; API'yi yeniden başlat (bkz. "Yeniden başlatma"), olay kaydı aç
Eskalasyon: 15 dk içinde düzelmezse → veritabanı nöbetçisi (+90 …)

Runbook iki kaynaktan beslenir: her postmortem (15-11'in 5 neden'i, suçsuz) "runbook'ta bu eksikti" maddesi üretir; her yeni alarm tanımı runbook'a satır olmadan CI'dan geçmez. Ve test edilir: sistemi tanımayan birine sahte alarm verilir, adımları izleyip izleyemediği ölçülür (game day). Adımlar çalıştırılmadıysa runbook yoktur, niyet vardır.

08Mimari diyagram: C4 ve diyagram-kod

Bir diyagramın iki ölümcül hastalığı vardır: her şeyi tek resme sığdırmak (kimse okuyamaz) ve kodla birlikte güncellenmemek (yalan söyler). C4 modeli birincisini çözer: dört yakınlaştırma düzeyi, her düzeyde tek soru.

Çoğu proje 1 ve 2'yle yaşar; 3 yalnız karmaşık konteynerler için. İkinci hastalığı diyagram-kod çözer: diyagram bir metin dosyasıdır (Mermaid, PlantUML), depoda yaşar, PR'da diff'i görülür, platform onu çizer:

```mermaid
C4Context
  Person(aday, "Aday", "Sınava başvuran kişi")
  System(api, "Başvuru Sistemi", "Başvuru alır, doğrular, durum bildirir")
  System_Ext(oidc, "Kurum OIDC", "Kimlik doğrulama")
  System_Ext(edevlet, "e-Devlet", "Kimlik ve adres doğrulama")
  Rel(aday, api, "Başvuru yapar", "HTTPS")
  Rel(api, oidc, "Token doğrular", "OIDC")
  Rel(api, edevlet, "Kimlik sorgular", "SOAP/HTTPS")
```

Sıralı (sequence) diyagram, bir isteğin servisler arası yolculuğunu anlatmak için (19. hat); veri akışı diyagramı (DFD) 14-02'nin tehdit modelinin girdisidir — C4 konteyner diyagramı çoğu zaman DFD'nin kendisidir, güven sınırları çizilerek. Kural: diyagram yalan söylemeye başladığı gün ya güncellenir ya silinir.

09Teknik yazım ilkeleri ve kamu teslimatı

İyi teknik metin, iyi koda benzer: okuyucu için yazılır, kısa, tek anlamlı, test edilmiş. İlkeler:

• Önce okuyucu ve amacı: "kim, ne yapmak istiyor" — 02. bölümün türü buradan seçilir; bir belgede türleri karıştırma.
• Sonuç önce: ilk cümle cevabı verir, gerekçe sonra gelir (nöbetçi 3. paragrafı okumaz).
• Kısa cümle, etken çatı, tek terim: "başvuru" bir yerde "müracaat" olmaz; terimler sözlüğü (9. dersin SRS'inin bir bölümü) tutulur. Emir kipi adımlarda: "Çalıştırın" değil "Çalıştır" — ya da tutarlı olarak biri.
• Örnek ve komut: soyut açıklamanın yanına somut örnek; komutlar kopyalanabilir ve çalıştırılarak doğrulanmış. Doğrulanmamış komut, bozuk bağlantı gibidir.
• Sahip ve tarih: her belgenin sahibi ve son gözden geçirme tarihi vardır; bayatlık görünür olur.
• Gözden geçirme: doküman PR'ı kod PR'ı gibi incelenir; hedef okuyucuya yakın biri (yeni gelen) en iyi inceleyendir.
• Kod içi açıklama en düşük değerli doküman türüdür: önce isim ve test konuşur; yazılacaksa "ne"yi değil "neden"i (bir tuzağı, bir dış kısıtı) söyler ve kodla birlikte bakımı yapılır — bayat açıklama, bayat diyagram gibi yanıltır.

Kamu teslimat dokümanları 9. dersin zincirinden gelir ve yazım tarafı bu dersin konusudur: analiz dokümanı (SRS — gereksinim + kabul kriteri + izlenebilirlik; açıklama ve referans türü), tasarım dokümanı (SDD — C4 + ADR'ler + veri modeli + arayüz sözleşmesi), test planı ve raporu (referans), kullanıcı kılavuzu (öğretici + kılavuz), kurulum kılavuzu ve işletim el kitabı (runbook). Şartname bunları çoğu zaman biçim ve numara düzeniyle ister; docs-as-code depo bunları Markdown'dan PDF'e üretebilir (18. hat CI adımı). Kurum tarafındaki uzman için ters yönde de geçerli: yükleniciden gelen dokümanı bu ilkelerle incelemek — örneği olmayan API dokümanı, kabul kriteri olmayan gereksinim, komutu doğrulanmamış kurulum kılavuzu kabul edilmez.

10Mini alıştırma — deponun dokümanını kur

11Kendini sına

Dokümantasyonun dört türü nedir ve neden ayrılır? Docs-as-code ne demektir; wiki'nin sorunu ve "dokümantasyon borcu" nedir? README'nin ölçütü ve iskeleti nedir?

Dört tür okuyucunun durumuna göre ayrılır: öğretici (öğreniyor; adım adım, garantili sonuç — README'nin ilk beş dakikası), kılavuz (bir işi yapmak istiyor; görev odaklı — runbook), referans (ayrıntıya bakıyor; tam ve kuru — OpenAPI, yapılandırma tablosu), açıklama (neden böyle — ADR, mimari genel bakış); tek belge hepsine hitap edemez, türler karıştırılmaz. Docs-as-code: doküman Markdown olarak kodla aynı depoda, aynı PR'da değişir, aynı incelemeden geçer, CI bozuk bağlantıyı yakalar, sürümle tag'lenir. Wiki koddan ayrı yaşar, PR onu güncellemeye zorlamaz, altı ayda bayatlar; bayat doküman olmayandan kötüdür çünkü okuyucu güvenip yanlış yapar. Dokümantasyon borcu: bilerek yazılmayan dokümanın kayda geçmesi ve faiz işlemesi (her yeni gelen aynı soru, her nöbetçi aynı keşif). README ölçütü: hiç görmemiş biri beş dakikada kurup çalıştırıp testleri koşturabilmeli; iskelet: tek cümle ne, gereksinimler, kopyalanabilir ve doğrulanmış kurulum komutları, yapılandırma tablosu (zorunlu/varsayılan/açıklama; sırlar kasadan), test, dağıtım/katkı/lisans bağlantıları; büyüyünce docs/'a dallanır; komşular CONTRIBUTING, SECURITY, CODEOWNERS.

ADR nedir, hangi bölümlerden oluşur, üç kuralı nedir? Ne zaman yazılır? Önceki hatların hangi ihtiyaçları ADR'de karşılanır?

Architecture Decision Record: "neden"in kaybolmasına karşı kısa, numaralı, değişmez karar belgesi. Bölümler: başlık ve durum (önerildi / kabul edildi / geçersiz kılındı → hangisi tarafından), bağlam (karar anındaki gerçekler ve kısıtlar — değişirse karar gözden geçirilir), değerlendirilen seçenekler (reddedilen en az seçilen kadar değerli), karar (tek cümle), sonuçlar (artı ve eksiler, kabul edilen artık risk ve sahibi, doğan teknik borç). Üç kural: numaralı ve sıralı (docs/adr/0007-…); değişmez — karar değişirse yeni ADR yazılır, eskisi "geçersiz kılındı" olur, tarih okunur; kısa — uzun tasarım dokümanı ayrı, ADR bağlantı verir. Ne zaman: geri dönüşü pahalı kararlar (veritabanı, kimlik mimarisi, mesajlaşma, dil/çerçeve), ekibi bağlayan kararlar (dal stratejisi, süreç modeli, kodlama standardı), altı ay sonra "neden" diye sorulacak her karar; "değişken adı" ADR değildir; kararı uygulayan PR ADR'yi de getirir. Karşılanan ihtiyaçlar: güvenlik kararının gerekçeli kaydı (13-01), artık risk kabulünün risk sahibi adıyla yazılması (14-02) → sonuçlar bölümü, güvenli geliştirme kararları (14-09), denetçiye "ne zaman, kim, neden" kanıtı (14-11), bilinçli teknik borcun doğduğu yer (15-11).

Tam bir API dokümanı OpenAPI'nin ötesinde ne içerir? Keep a Changelog biçimi nedir ve Conventional Commits'ten nasıl otomatik üretilir; otomasyonun sınırı nedir?

OpenAPI yalnız referanstır; tam doküman: başlangıç kılavuzu (kimlik alma, ilk istek, kopyalanabilir curl, beş dakika), her uç için gerçekçi örnek istek/yanıt (örneği olmayan uç dokümante edilmemiştir; OpenAPI example alanları), hata tablosu (Problem Details, hangi kod ne zaman, tüketici ne yapmalı), sürüm ve deprecation politikası (destek penceresi, Deprecation/Sunset başlıkları), sınırlar (hız, sayfalama), changelog; iç API'de de geçerli, iki ekibin sözleşmesi; açıklama ve örnekler OpenAPI belgesinde tek kaynak, Markdown kılavuz çevreler, aynı PR'da değişir. Keep a Changelog: en yeni üstte, her sürüm tarihli, Unreleased bölümü biriktirir, altı bölüm — Added, Changed, Deprecated, Removed, Fixed, Security — her satır iş kaydına bağlı. Otomasyon: feat → Added/MINOR, fix → Fixed/PATCH, feat! ya da BREAKING CHANGE → Changed-Removed + MAJOR, docs/chore/refactor/test girmez; araç son tag'den bu yana commit'leri okur, sürümü hesaplar, CHANGELOG'u üretir, annotated tag atar, Release notu açar (semantic-release, release-please; .NET'te GitVersion sürüm hesabı). Sınırı: üretilen changelog taslaktır — insan tüketici gözüyle okur, iç ayrıntı satırlarını atar, kırıcı değişikliğe geçiş yönergesi ekler; tag, changelog ve Release notu aynı sürüm numarasını taşır.

Runbook kime, nasıl yazılır ve nasıl test edilir? C4 modelinin düzeyleri nelerdir; diyagram-kod neden gerekir? Teknik yazımın temel ilkeleri nelerdir?

Runbook sistemi yazmamış, uykusuz nöbetçiye yazılır; ölçütü: sistemi tanımayan biri alarmdan kurtarmaya beş dakikada geçebilmeli. İçerik: servis özeti ve eskalasyon zinciri, bağımlılıklar ve "çökerse ne olur", nereye bakılır (sağlık ucu, dashboard, kopyalanabilir log sorguları, korelasyon kimliği), alarm → adım (belirti, ilk kontrol, olası neden, müdahale, eskalasyon eşiği; kılavuz türü, numaralı, tek yol), prosedürler (yeniden başlatma, geri alma, bakım modu, yedekten dönüş, sır döndürme), bilinen sorunlar ve postmortem bağlantıları. Beslenmesi: her postmortem "runbook'ta bu eksikti" maddesi üretir; yeni alarm runbook satırı olmadan girmez. Testi: game day — sistemi tanımayan birine sahte alarm, adımları izleyebiliyor mu; çalıştırılmamış adım niyettir. C4: bağlam (sistem dünyada nerede: kullanıcılar, dış sistemler), konteyner (çalışan parçalar: web, API, veritabanı, kuyruk), bileşen (bir konteynerin içi), kod (genelde gereksiz); her düzeyde tek soru; çoğu proje 1-2 ile yaşar; konteyner diyagramı güven sınırlarıyla tehdit modelinin DFD'sidir. Diyagram-kod (Mermaid/PlantUML): metin dosyası, depoda, PR'da diff, platform çizer — "kodla güncellenmeyen diyagram yalan söyler; güncelle ya da sil". Yazım ilkeleri: önce okuyucu ve amaç (tür seçimi), sonuç önce, kısa cümle/etken çatı/tek terim (sözlük), örnek ve çalıştırılarak doğrulanmış komut, sahip ve tarih, doküman PR'ının incelenmesi (yeni gelen en iyi inceleyen), kod içi açıklama en düşük değerli tür — önce isim ve test, yazılacaksa "neden".

12Sınav köşesi