22 — Dokümantasyon Platformu (Documentation Platform)

Kısa özet: Teknik dokümanların yazıldığı, sürümlendiği ve yayınlandığı platform kararı: Docusaurus önerilir. docs/*.md tek kaynaktır; site derlemesi CI'da yapılır; AI ajanları Markdown'u doğrudan günceller.

Dosya: docs/22-DOCUMENTATION-PLATFORM.md
İlgili kararlar: 24-DECISION-LOG.md#K-08 (Docusaurus, MkDocs yedekte)
Durum: [ ] Taslak

1. Amaç

27 dokümanın (00…25 + şablon) hem ham Markdown olarak Git'te hem de aranabilir site olarak yayınlanmasını sağlamak; "doküman nerede, güncel mi, kim değiştirdi" sorularını kapatmak.

2. Kapsam

Kapsam içi: platform seçimi, docs/ ↔ site ilişkisi, yazım-derleme-yayın akışı, sürümleme ve dil politikası.
Kapsam dışı: doküman içerikleri (00…21, 23…25), CI komut detayı (25-ROADMAP'a havale).

3. Kararlar

KARAR:    Dokümantasyon platformu Docusaurus'tur; kaynak `docs-site/` iskeleti + `docs/*.md` tek-kaynak; site derlemesi CI'da yapılır.
GEREKÇE:  "AI-güncelleme" kriterini yalnızca Git-yerleşik Markdown çözer: ajan `.md`'yi doğrudan yazar, değişiklik PR'dan geçer, geçmiş Git'tedir. Docusaurus yerleşik sürümleme + yerleşik i18n + MDX (Mermaid dahil) verir; derleme maliyeti alternatifleriyle eşdeğerdir.
ALTERNATİF: MkDocs + Material — eşdeğer sadelikte güçlü ikinci; Docusaurus hattı sorun çıkarırsa geçiş maliyeti düşük (kaynak yine düz Markdown) → yedekte tutulur. Wiki.js (DB+servis yükü) ve TriliumNext (tek kullanıcı) elendi.
RİSK:     Node derleme hattı bozulabilir; azaltma: kilitli bağımlılıklar + CI derleme testi; derleme bozulsa bile `docs/*.md` ham haliyle okunur.
MALİYET:  Ücretsiz (self-hosted/statik yayın).
LİSANS:   Docusaurus MIT — https://github.com/facebook/docusaurus + https://docusaurus.io/docs/markdown-features/diagrams (doğrulanma: 2026-09-15).

KARAR:    Yayınlanan sitenin kaynağı ile Git'teki `docs/*.md` arasında elle kopyalama yapılmaz; senkronizasyon tek yönlüdür (Git → site).
GEREKÇE:  Çift-kaynak, güncel-olmayan site üretir; tek kaynak + CI derlemesi "sitedeki her satırın Git karşılığı var" garantisi verir.
ALTERNATİF: Wiki'de düzenle, Git'e aktar — yön tersine döner, PR disiplini ölür; elendi.
RİSK:     CI bozulursa site eskir; azaltma: CI rozeti + derleme testi her PR'da koşar.
MALİYET:  Ücretsiz.
LİSANS:   Yok.

4. Neden Bu Karar?

Üç filtre (24 §4) burada da uygulandı: (1) ücretsiz — Docusaurus MIT, barındırma statik; (2) sadelik — DB'li wiki (Wiki.js) bir servis daha demektir, reddedildi; tek-kullanıcı bilgi tabanı (TriliumNext) ekip akışını taşımaz; (3) AI-uyumluluk — ajan düz Markdown'u yazar ve review'a sunar; bu, DB-içi editörde mümkün değildir. MkDocs'a karşı Docusaurus'u ayıran, sonradan eklenti aramadan gelen sürümleme + i18n'dir (700 cihazlık filonun dokümanı yıllarca yaşar, sürüm gerekir).

5. Alternatifler

Alternatif	Artı	Eksi	Sonuç
MkDocs + Material	Sade, hızlı, güçlü ikinci	Sürümleme/i18n eklentiyle	Yedek
Wiki.js	Güçlü editör, yetkilendirme	DB+servis yükü, Git akışı dolaylı	Elendi
TriliumNext	Hafif, kişisel	Ekip review akışı yok	Elendi
Yalnızca GitHub/GitLab render	Sıfır kurulum	Sürümleme/arama/zengin tema yok	Elendi (ham okuma zaten var)

6. Avantajlar

Derleme bozulsa bile dokümanlar kaybolmaz (docs/*.md her zaman okunur).
Mermaid diyagramları (01'deki 3 akış) sitede ve PR önizlemede render olur.
Sürümleme sayesinde "PİLOT'taki prosedür neydi" sorusu cevaplanabilir.

7. Dezavantajlar

Node derleme hattı bakım ister (kilit dosyası + periyodik güncelleme).
Editör eşiği wiki'ye göre yüksektir (PR açmak gerekir) — teknik ekip için kabul edilebilir.

8. Riskler

Risk	Olasılık	Etki	Azaltma
Derleme hattı bozulur, site eskir	Orta	Düşük (kaynak okunur)	CI derleme testi + kilitli bağımlılık
Doküman-Git senkronu bozulur (elle site editi)	Düşük	Orta	Siteye yazma yetkisi yalnızca CI'da
İçerik eskir (prosedür değişti, doküman kalmış)	Orta	Yüksek	Her PR'da "ilgili doküman güncellendi mi" kontrolü

9. Uygulama Planı

docs-site/ iskeleti kurulur (Docusaurus init), docs/*.md siteye kaynak olarak bağlanır.
CI job'ı: her PR'da derleme testi (build); main'e merge'de statik yayın.
Yazım kuralı: yeni/degisen prosedür → önce .md, sonra PR; site editi yasak.
Sürümleme: ilk PROD dalgasında v1 kesilir; sonraki imaj değişiklikleri yeni sürümle etiketlenir.

# örnek: yerelde önizleme (komut adları İngilizce orijinal, açıklama Türkçe)
cd docs-site
npm install
npm run build
npm run serve

10. Test Planı

Test	Beklenen sonuç	Ortam
CI derleme testi (bozuk link/Mermaid)	Hatalı PR kırmızıya düşer	CI
`docs/*.md` ham okunabilirlik	Git arayüzünde tablolar/diyagramlar anlaşılır	Git web
Sürüm kesme (`v1`)	Eski prosedüre sürüm menüsünden erişilir	Yayınlanan site

11. Rollback

Bozuk site yayını: önceki CI çıktısına (statik) dönülür; kaynak .md etkilenmez.
Platform değişikliği (Docusaurus → MkDocs): kaynak .md taşındığı için içerik kaybı olmaz; yalnızca docs-site/ yeniden yazılır.

12. Kontrol Listesi

docs-site/ derleniyor, 3 Mermaid (01) render oluyor.
CI'da derleme testi her PR'da koşuyor.
Siteye elle yazma kapalı (yalnızca CI yayınlıyor).
Şablon (_TEMPLATE.md) ile yeni doküman açma akışı denendi.

13. Açık Sorular

Statik sitenin barındırılacağı yer (merkez VDS / iç ağ) (sahibi: 25-ROADMAP).
İlk sürüm (v1) kesme tarihi — PROD dalgasına bağlı (sahibi: merkezi admin, 21).
Türkçe dışına çeviri ihtiyacı (i18n açılacak mı) (sahibi: yönetim).

Ek: Mermaid — doküman akışı

flowchart LR
    W["Yazar/ajan<br/>docs/*.md düzenler"] --> PR["PR + review"]
    PR --> CI["CI: Docusaurus build testi"]
    CI -->|yeşil| MERGE["main'e merge"]
    MERGE --> PUB["Statik site yayını"]
    PUB --> READ["Okuyucu<br/>(teknisyen/admin)"]

6.3 KiB Raw Permalink Blame History Unescape Escape