Şirket İçi Dokümantasyon Standartları: GitHub ve Confluence Rehberi

[melihcelenk]

Şirket İçi Dokümantasyon Standartları: GitHub ve Confluence Rehberi

Yazılım dünyasında kod yazmak işin sadece yarısıdır; diğer yarısı ise o kodun "ne yaptığını", "nasıl çalıştığını" ve "neden orada olduğunu" anlatmaktır. İyi dokümantasyon, sizi "Bu modül ne işe yarıyordu?" diye sormaktan veya işten ayrılan bir arkadaşın ardından kaybolan bilgilerden korur.

Bu rehberde, modern dokümantasyon standartlarını, yaklaşım farklarını ve GitHub/Confluence ikilisini nasıl verimli kullanabileceğimizi ele alacağız.

────────────────────────────────────────────────────────────────────────────────

1. Temel Yaklaşımlar: Kime, Nasıl Yazıyoruz?

Dokümantasyon yazarken düşülen en büyük hata, okuyucunun sizin bildiğiniz her şeyi bildiğini varsaymaktır. Burada iki kritik kavram devreye girer:

ELI5 (Explain Like I’m Five - Beş Yaşındaymışım Gibi Anlat)
Bu yaklaşım, konuyu aptallaştırmak değil, sadeleştirmektir. Karmaşık jargonları bir kenara bırakıp, özü anlatmaya odaklanırız.

• Yanlış: "TCP handshake timeout olduğu için latency spike yaşandı."
• Doğru (ELI5): "Sunucuyla selamlaşmamız çok uzun sürdüğü için bağlantıda gecikmeler oldu."
• Kullanım Alanı: README girişleri, Confluence "Onboarding" sayfaları, Proje özetleri.

Beginner vs. Advanced Ayrımı
Her okuyucu aynı seviyede değildir. Dokümanı iki katmana ayırmak gerekir:

• Beginner (Başlangıç): "Bu proje ne işe yarar?", "Nasıl kurarım?", "İlk 'Hello World'ü nasıl çalıştırırım?". Hedef: Kullanıcıyı en hızlı şekilde başarıya ulaştırmak (Quick Start).
• Advanced (İleri Seviye): "Mimari yapı nasıldır?", "Veritabanı şeması nedir?", "API uç noktalarının detayları nelerdir?". Hedef: Sistemin derinliklerine inmek ve özelleştirmek isteyenlere rehberlik etmek.

────────────────────────────────────────────────────────────────────────────────

2. Hangi Standart Nerede Kullanılır? (Karşılaştırma Tablosu)

Şirket ihtiyaçlarına göre doğru standardı seçmek hayat kurtarır. İşte en yaygın metodolojiler:

Kod: Tümünü seç

┌─────────────────────────┬──────────────────────┬──────────────────────────────┬──────────────────────────────────────────┬─────────────────────────────────────┐
│ Standart / Çerçeve      │ Platform             │ Temel Amaç                   │ ELI5 & Netlik Yaklaşımı                  │ Kaynak / Link                       │
├─────────────────────────┼──────────────────────┼──────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────────────┤
│ Diátaxis Framework      │ GitHub (docs/), Wiki │ Bilgi Mimarisi (Niyet)       │ Okuyucuyu boğmaz; "Öğren" ve "Çöz"       │ diataxis.fr                         │
│                         │                      │                              │ modlarını birbirinden ayırır.            │                                     │
├─────────────────────────┼──────────────────────┼──────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────────────┤
│ Google Dev. Style Guide │ GitHub (README, API) │ Dil ve Ton Standartlaşması   │ "Biz" yerine "Sen" (You) dilini savunur. │ developers.google.com/style         │
│                         │                      │                              │ Dostane ve emir kipindedir.              │                                     │
├─────────────────────────┼──────────────────────┼──────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────────────┤
│ Microsoft Style Guide   │ Confluence, UI Metin │ Kapsayıcılık & Kurumsal Dil  │ "Plain Language" (Yalın Dil) kuralı çok  │ learn.microsoft.com/style-guide     │
│                         │                      │                              │ katıdır. Belirsizliği yok eder.          │                                     │
├─────────────────────────┼──────────────────────┼──────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────────────┤
│ Docs-as-Code            │ GitHub               │ Süreç Yönetimi (Ver. Ctrl)   │ Doküman da kod gibi yaşar. Bayat bilgi   │ writethedocs.org/guide/docs-as-code │
│                         │                      │                              │ kafa karışıklığı yaratır.                │                                     │
├─────────────────────────┼──────────────────────┼──────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────────────┤
│ C4 Model                │ Confluence & GitHub  │ Mimari Görselleştirme        │ Karmaşık sistemi katman katman (Harita   │ c4model.com                         │
│                         │                      │                              │ gibi) basitten zora doğru çizer.         │                                     │
└─────────────────────────┴──────────────────────┴──────────────────────────────┴──────────────────────────────────────────┴─────────────────────────────────────┘

────────────────────────────────────────────────────────────────────────────────

3. Platform Stratejisi: GitHub vs. Confluence

• GitHub: Kodun yaşadığı yerdir. Teknik dokümantasyon, kurulum, API detayları ve sürüm notları burada olmalı. (Geliştiriciye yakın).
• Confluence: İşin yönetildiği yerdir. Ürün gereksinimleri, toplantı notları, mimari kararlar (ADR), ekip süreçleri ve onboarding burada olmalı. (Tüm şirkete yakın).

Örnek GitHub Klasör Yapısı (Best Practice)
Bir repository içinde README.md vitrininizdir, docs/ klasörü ise kütüphanenizdir.

Kod: Tümünü seç

project-root/
├── README.md           # Projenin "Asansör Konuşması" (Vitrin)
├── CONTRIBUTING.md     # "Nasıl katkı sağlarım?" rehberi
├── CHANGELOG.md        # Sürüm geçmişi
└── docs/               # Detaylı dokümantasyon (Diátaxis yapısı)
    ├── tutorials/      # Adım adım başlangıç dersleri (Öğrenme)
    │   └── getting-started.md
    ├── how-to/         # Belirli senaryolar için çözümler (Problem Çözme)
    │   └── configure-auth.md
    ├── reference/      # Teknik API ve konfigürasyon detayları (Bilgi)
    │   └── api-endpoints.md
    └── explanations/   # Mimari kararlar ve konseptler (Anlama)
        └── architecture-overview.md

İdeal Bir README.md İskeleti:
1. Başlık & Logo: Projenin adı.
2. Rozetler (Badges): Build durumu, versiyon, lisans.
3. Kısa Açıklama (ELI5): Bu proje ne yapıyor?
4. Hızlı Başlangıç (Quick Start): 3 komutla projeyi ayağa kaldırma.
5. Kullanım Örnekleri: Basit kod blokları.
6. Dokümantasyon Linki: docs/ klasörüne yönlendirme.

────────────────────────────────────────────────────────────────────────────────

Özetle: İyi dokümantasyon, gelecekteki kendinize (veya gece 3'te bug çözen ekip arkadaşınıza) yazdığınız bir aşk mektubudur. Basit anlatın, yapıyı kurun, bilgiyi doğru yerde saklayın.