Dokümantasyon Katkısı

BERK'in dokümantasyonunu geliştirmeye katkıda bulunmak için rehber. Her türlü dokümantasyon katkısı değerlidir!

📚 Dokümantasyon Türleri

1. mdBook Dokümantasyonu

Ana dokümantasyon kitabı (şu anda okuduğunuz)

• Konum: berk-lang/book/src/
• Format: Markdown (.md)
• Tool: mdBook

2. API Dokümantasyonu

Rust kod içi doc comments

• Konum: berk-lang/src/
• Format: Rustdoc comments (///)
• Tool: cargo doc

3. Stdlib Dokümantasyonu

Standard library modül açıklamaları

• Konum: stdlib/*.berk
• Format: BERK doc comments (///)

4. GitHub Pages

Publish edilmiş HTML dökümanlar

• Konum: berk_pages repository
• URL: https://arslantasm.github.io/berk_pages/

🛠️ Dokümantasyon Geliştirme Ortamı

mdBook Kurulumu

# mdBook yükleme
cargo install mdbook

# Opsiyonel: Live reload için
cargo install mdbook-serve

Dokümantasyonu Yerel Olarak Görüntüleme

cd berk-lang/book

# Build
mdbook build

# Serve (localhost:3000)
mdbook serve

# Tarayıcıda aç
# http://localhost:3000

📝 Markdown Stil Rehberi

Başlıklar

# Ana Başlık (H1) - Sadece sayfa başlığı için

## Bölüm Başlığı (H2) - Ana konular

### Alt Başlık (H3) - Alt konular

#### Küçük Başlık (H4) - Detaylar

Kod Blokları

```berk
fonksiyon merhaba() {
    yazdır("Merhaba Dünya!")
}
```

```rust
pub fn hello() {
    println!("Hello World!");
}
```

```bash
cargo build --release
```

Inline Kod

`değişken`, `fonksiyon`, `Result` gibi inline kod için backtick kullanın.

Linkler

// İç link
[Anahtar Kelimeler](./reference/keywords.md)

// Dış link
[Rust Documentation](https://doc.rust-lang.org)

// Anchor link
[Bölüm 2](#bölüm-2)

Listeler

// Sırasız liste
- Birinci öğe
- İkinci öğe
  - Alt öğe
  - Alt öğe 2

// Sıralı liste
1. İlk adım
2. İkinci adım
3. Üçüncü adım

Tablolar

| Türkçe | İngilizce | Açıklama |
|--------|-----------|----------|
| `değişken` | `let` | Değişken tanımlama |
| `fonksiyon` | `fn` | Fonksiyon tanımlama |

Admonitions (Uyarılar)

> **💡 Not:** Bu önemli bir bilgidir.

> **⚠️ Uyarı:** Bu tehlikeli olabilir.

> **✅ İpucu:** Bunu deneyin!

📖 İçerik Yazma Rehberi

Dil ve Ton

• ✅ Açık ve net olun
• ✅ Örneklerle açıklayın
• ✅ Başlangıç seviyesine uygun yazın
• ✅ Teknik terimler için açıklama ekleyin
• ❌ Jargon kullanmaktan kaçının (gerekmedikçe)

Yapı

1. Giriş - Konuyu tanıtın
2. Temel Kavramlar - Öğrenilecekler
3. Örnekler - Pratik kullanım
4. Best Practices - İpuçları
5. İleri Konular - Detaylı bilgi

Örnek Şablon

# Başlık

## Giriş
Kısa tanıtım paragrafı...

## Temel Kullanım
```berk
// Basit örnek
```

## Parametreler
| Parametre | Tip | Açıklama |
|-----------|-----|----------|
| `x` | `tam` | Giriş değeri |

## Örnekler

### Örnek 1: Basit Kullanım
```berk
// Kod
```

### Örnek 2: İleri Seviye
```berk
// Kod
```

## Best Practices
> **💡 İpucu:** ...

## İlgili Kaynaklar
- [Link 1](...)
- [Link 2](...)

🔧 Stdlib Dokümantasyonu

Fonksiyon Dokümantasyonu

/// İki sayıyı toplar ve sonucu döndürür.
///
/// Bu fonksiyon iki tam sayı alır ve toplamlarını hesaplar.
/// Overflow kontrolü yapmaz.
///
/// # Parametreler
/// * `a` - İlk sayı
/// * `b` - İkinci sayı
///
/// # Döndürür
/// İki sayının toplamı
///
/// # Örnekler
/// ```berk
/// değişken sonuç = topla(5, 3)  // 8
/// değişken büyük = topla(1000000, 2000000)  // 3000000
/// ```
///
/// # Hata Durumları
/// Overflow durumunda tanımsız davranış
fonksiyon topla(a: tam, b: tam) -> tam {
    döndür a + b
}

Modül Dokümantasyonu

/// # math - Matematik Fonksiyonları
///
/// Temel ve ileri matematiksel işlemler için fonksiyon koleksiyonu.
///
/// ## Kategoriler
/// - **Temel:** toplam, çıkar, çarp, böl
/// - **Trigonometri:** sin, cos, tan
/// - **Logaritma:** log, ln, log10
/// - **Üs:** pow, sqrt, cbrt
///
/// ## Kullanım
/// ```berk
/// içe_aktar math
///
/// değişken sonuç = math.pow(2, 10)  // 1024
/// değişken kök = math.sqrt(16)      // 4.0
/// ```

// Modül kodu...

🎨 HTML Sayfaları (GitHub Pages)

Yapı

mdBook tarafından otomatik generate edilir, ancak özel sayfalar için:

<!-- stdlib/yeni-modul.html -->
<div class="module-header">
    <h1>📦 yeni-modul - Modül Açıklaması</h1>
    <p>Kısa tanıtım</p>
    <div class="module-stats">
        <div class="stat-badge">
            <div style="font-size:2em">15</div>
            <div>Fonksiyon</div>
        </div>
    </div>
</div>

✅ Dokümantasyon Checklist

Yeni Sayfa Eklerken

• ☑️ SUMMARY.md'ye eklendi mi?
• ☑️ Başlık ve meta bilgiler doğru mu?
• ☑️ Kod örnekleri test edildi mi?
• ☑️ Linkler çalışıyor mu?
• ☑️ Görseller varsa yüklendi mi?
• ☑️ Yazım hatası kontrolü yapıldı mı?

Düzenleme Yaparken

• ☑️ Değişiklik anlamlı mı?
• ☑️ Eski bilgiler güncel mi?
• ☑️ Yeni özellikler eklendi mi?
• ☑️ Deprecated bilgiler kaldırıldı mı?

🚀 Dokümantasyon Publish

GitHub Pages Güncelleme

# mdBook build
cd berk-lang/book
mdbook build

# berk_pages repository'ye kopyala
cp -r book/html/* ../../berk_pages/

# Commit ve push
cd ../../berk_pages
git add .
git commit -m "docs: dokümantasyon güncellendi"
git push origin main

# GitHub Pages otomatik deploy eder (~2-3 dakika)

API Docs Publish

# Rustdoc oluşturma
cd berk-lang
cargo doc --no-deps --open

# docs/ klasörüne kopyala
cp -r target/doc docs/api

💡 İyi Pratikler

• ✅ Her örnek çalışır olmalı
• ✅ Örnekler minimal olmalı (tek konsept)
• ✅ Türkçe ve İngilizce örnekler verin
• ✅ Hata durumlarını açıklayın
• ✅ Performans notları ekleyin (gerekiyorsa)
• ✅ İlgili sayfalara link verin
• ✅ Görseller kullanın (diagram, screenshot)

📊 Kalite Metrikleri

• Coverage: Tüm public API dokümante edilmeli
• Örnekler: Her fonksiyon minimum 1 örnek
• Güncellik: Deprecated özellikler işaretlenmeli
• Bağlantılar: Kırık link olmamalı

📞 Dokümantasyon Sorunları

• Eksik bilgi mi var? Issue açın
• Yanlış bilgi mi? PR gönderin
• Anlaşılmaz mı? Discussion başlatın
• Çeviri hatası mı? Düzeltin ve PR açın

🔗 Kaynaklar

• mdBook Documentation
• Rustdoc Guide
• Write the Docs
• Google Technical Writing