GitHub Wiki ile Proje Dokümantasyonu Nasıl Yapılır

Yıllarca “dokümantasyon sonra yazılır” diyerek ertelediğim şeyler, beni sonunda buldu. Bir projeyi devretmek zorunda kaldığımda, üç yıl önce yazdığım servisin neden öyle çalıştığını açıklayacak tek bir satır bile yoktu. O günden sonra GitHub Wiki benim için bir alışkanlık haline geldi; şimdi size bu alışkanlığın nasıl çalıştığını anlatacağım.

GitHub Wiki Nedir ve Neden Önemlidir

GitHub Wiki, her repository ile birlikte gelen, Markdown tabanlı bir dokümantasyon platformudur. README dosyanızın “bu projeye nasıl merhaba denir” kısmının ötesine geçmek istediğinizde, Wiki devreye girer. Kurulum rehberlerinden mimari kararlarına, API referanslarından sorun giderme notlarına kadar her şeyi organize biçimde tutabilirsiniz.

Ama asıl değeri şuradan geliyor: Wiki, ayrı bir Git repository’sidir. Yani sürüm kontrolü altındadır, clone edilebilir, local olarak düzenlenebilir ve pull request dışında doğrudan push edilebilir. Bu son nokta önemli çünkü dokümantasyon yazarken PR süreci bazen sürtünme yaratır. Bir cümleyi düzeltmek için PR açmak zorunda kalmazsınız.

Wiki’yi Aktifleştirmek ve İlk Yapıyı Kurmak

Repository ayarlarında Wiki özelliği varsayılan olarak açık gelir. Eğer private bir repo kullanıyorsanız ve Wiki’ye kimin yazabileceğini kontrol etmek istiyorsanız, Settings > General > Features altından “Restrict editing to collaborators only” seçeneğini işaretleyin.

İlk sayfayı web arayüzünden oluşturabilirsiniz ama ben her zaman local çalışmayı tercih ederim. Wiki’yi clone’lamak için:

# Ana repo URL'inizin sonuna .wiki.git ekleyin
git clone https://github.com/kullaniciadiniz/projeadi.wiki.git

cd projeadi.wiki
ls -la
# Home.md dosyası otomatik oluşmuş olacak

Clone ettikten sonra dosya yapınızı düzenleyebilirsiniz. GitHub Wiki, klasör hiyerarşisini desteklemez; tüm sayfalar aynı dizinde yaşar. Bu bir kısıtlama gibi görünse de sayfa adlandırma konvansiyonuyla aşılabilir:

# Düz dosya yapısıyla kategori simülasyonu
touch Home.md
touch Kurulum-Linux.md
touch Kurulum-Windows.md
touch API-Referans-Genel.md
touch API-Referans-Kimlik-Dogrulama.md
touch Sorun-Giderme-Servis-Baslatilamadi.md
touch Mimari-Karar-Kayitlari.md

git add .
git commit -m "İlk wiki yapısı oluşturuldu"
git push origin master

Home.md: Kapı Sayfasını Doğru Tasarlamak

Home.md dosyası ziyaretçilerin ilk gördüğü sayfadır ve bir içindekiler tablosu görevi görmelidir. Uzun bir metin yazmak yerine, projenin ne olduğunu bir paragrafta özetle ve hızlıca ilgili sayfalara yönlendir.

## Projeye Hoş Geldiniz

Bu wiki, **OrderProcessing** servisi için teknik dokümantasyon içerir.
Servis, sipariş yaşam döngüsünü yönetir ve ödeme, stok, bildirim
servisleriyle entegre çalışır.

### Hızlı Başlangıç
- [Geliştirme Ortamı Kurulumu](Kurulum-Gelistirme)
- [Production Kurulumu](Kurulum-Production)
- [İlk Servis Çalıştırma](Ilk-Calistirma)

### Referans Dokümantasyon
- [API Endpointleri](API-Referans)
- [Konfigürasyon Parametreleri](Konfigurasyon)
- [Veritabanı Şema Değişiklikleri](Veritabani-Degisiklikler)

### Operasyonel Bilgiler
- [İzleme ve Alertler](Izleme-Alertler)
- [Sorun Giderme Rehberi](Sorun-Giderme)
- [Deployment Prosedürü](Deployment)

### Mimari ve Kararlar
- [Sistem Mimarisi](Mimari-Genel)
- [Mimari Karar Kayıtları](ADR)

Bağlantı yazarken dikkat edilmesi gereken nokta: GitHub Wiki, sayfa adlarındaki boşlukları tire ile değiştirir. “Kurulum Gelistirme” adlı sayfaya link verirken (Kurulum-Gelistirme) yazmanız gerekir.

Gerçek Dünya Senaryosu: Servis Kurulum Sayfası

Soyut konuşmak yerine, gerçekten işe yarayan bir kurulum sayfasının nasıl göründüğünü paylaşayım. Aşağıdaki yapıyı tüm projelerimde kullanıyorum:

cat > Kurulum-Production.md << 'EOF'
## Production Kurulumu

**Son güncelleme:** 2024-01 | **Test edildi:** Ubuntu 22.04, RHEL 9

### Gereksinimler

- Java 17 veya üzeri
- PostgreSQL 14+
- Redis 7+
- Minimum 4 GB RAM, 2 vCPU

### 1. Sistem Hazırlığı

Servisi çalıştıracak kullanıcıyı oluşturun:

    ```bash
    sudo useradd -r -s /bin/false -d /opt/orderprocessing orderproc
    sudo mkdir -p /opt/orderprocessing/{bin,config,logs,data}
    sudo chown -R orderproc:orderproc /opt/orderprocessing
    ```

### 2. Uygulama Dosyaları

    ```bash
    sudo tar -xzf orderprocessing-2.1.0.tar.gz -C /opt/orderprocessing/bin/
    sudo cp config/production.yml /opt/orderprocessing/config/app.yml
    sudo chown orderproc:orderproc /opt/orderprocessing/config/app.yml
    sudo chmod 640 /opt/orderprocessing/config/app.yml
    ```

### Bilinen Sorunlar

- RHEL 9'da SELinux politikası nedeniyle port 8080 için
  `semanage port -a -t http_port_t -p tcp 8080` komutu gerekebilir.
- Java 21 ile henüz test edilmedi, kullanmayın.

EOF

Dikkat edin: “Bilinen Sorunlar” bölümünü ekliyorum. Bu bölüm çok değerli çünkü bir kişinin bir saatte çözdüğü sorunu başkasının yaşamamasını sağlar.

Sidebar Kullanımı: Navigasyonu Kalıcı Hale Getirmek

GitHub Wiki’de _Sidebar.md adlı özel bir dosya oluşturursanız, bu dosyanın içeriği her sayfanın sağında görünür. Bu, büyük wiki’lerde navigasyonu kolaylaştırmanın en etkili yoludur.

cat > _Sidebar.md << 'EOF'
## Navigasyon

**Başlangıç**
- [Ana Sayfa](Home)
- [Hızlı Başlangıç](Hizli-Baslangic)

**Kurulum**
- [Geliştirme](Kurulum-Gelistirme)
- [Staging](Kurulum-Staging)
- [Production](Kurulum-Production)

**Referans**
- [API Dokümantasyonu](API-Referans)
- [Konfigürasyon](Konfigurasyon)
- [CLI Araçları](CLI-Araclar)

**Operasyon**
- [Deployment](Deployment)
- [İzleme](Izleme-Alertler)
- [Sorun Giderme](Sorun-Giderme)
- [Incident Geçmişi](Incident-Gecmisi)

**Mimari**
- [Genel Bakış](Mimari-Genel)
- [ADR Listesi](ADR)

EOF

git add _Sidebar.md
git commit -m "Sidebar navigasyon eklendi"
git push origin master

_Footer.md dosyası da benzer şekilde çalışır ve her sayfanın altında görünür. Buraya genellikle “Bu sayfa güncel değilse Slack’te #platform-team’i mention edin” gibi kısa notlar koyuyorum.

Wiki’yi Otomasyona Dahil Etmek

Wiki’nin ayrı bir Git repository olması, CI/CD pipeline’larına entegre etmeyi mümkün kılar. Mesela, uygulamanın versiyon numarası her release’de otomatik olarak Wiki’deki changelog sayfasına yazılabilir.

#!/bin/bash
# scripts/update-wiki-changelog.sh
# GitHub Actions veya Jenkins'ten çağrılır

WIKI_REPO="https://${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.wiki.git"
VERSION="${1}"
RELEASE_NOTES="${2}"

# Wiki'yi geçici dizine clone'la
TMPDIR=$(mktemp -d)
git clone "${WIKI_REPO}" "${TMPDIR}/wiki"

cd "${TMPDIR}/wiki"

# Changelog dosyasının başına yeni versiyonu ekle
TIMESTAMP=$(date '+%Y-%m-%d')
ENTRY="## ${VERSION} - ${TIMESTAMP}nn${RELEASE_NOTES}nn---nn"

# Mevcut içeriği koru, yeni girdiyi başa ekle
EXISTING=$(cat Changelog.md 2>/dev/null || echo "")
printf "%b%s" "${ENTRY}" "${EXISTING}" > Changelog.md

git config user.email "[email protected]"
git config user.name "CI Bot"
git add Changelog.md
git commit -m "Release ${VERSION} changelog güncellendi [skip ci]"
git push origin master

# Temizlik
rm -rf "${TMPDIR}"

Bu scripti GitHub Actions workflow’unuza eklemek için:

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  update-changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Changelog notlarını hazırla
        id: notes
        run: |
          # Git log'dan son tag'e kadar olan commit'leri al
          NOTES=$(git log --pretty="- %s" $(git describe --tags --abbrev=0 HEAD^)..HEAD)
          echo "notes=${NOTES}" >> $GITHUB_OUTPUT

      - name: Wiki'yi güncelle
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          bash scripts/update-wiki-changelog.sh 
            "${GITHUB_REF_NAME}" 
            "${{ steps.notes.outputs.notes }}"

Mimari Karar Kayıtları (ADR) Wiki’de Tutmak

Projede neden PostgreSQL seçildi? Neden monorepo yerine ayrı repolar tercih edildi? Bu kararları wiki’de belgelemek, aylarca sonra “bunu neden böyle yapmışız?” sorusunun cevabını vermek için kritiktir.

ADR sayfaları için standart bir format kullanıyorum:

cat > ADR-001-Veritabani-Secimi.md << 'EOF'
## ADR-001: Birincil Veritabanı Seçimi

**Durum:** Kabul edildi
**Tarih:** 2024-01-15
**Karar verenler:** Ahmet Y., Selin K., Platform Ekibi

### Bağlam

Sipariş verilerini saklamak için bir veritabanı seçmemiz gerekiyordu.
Yüksek yazma trafiği (saniyede ~500 yazma) ve karmaşık sorgular bekleniyor.

### Değerlendirilen Seçenekler

- **PostgreSQL 16:** ACID uyumlu, JSON desteği güçlü, ekipte bilgi birikimi var
- **MongoDB 7:** Esnek şema, yatay ölçekleme kolay ama ACID garanti yok
- **MySQL 8:** Bilinen teknoloji ama JSON desteği PostgreSQL kadar olgun değil

### Karar

PostgreSQL seçildi.

### Gerekçe

Sipariş verisinin tutarlılığı kritik olduğundan ACID garantisi önceliklidir.
Ekibin PostgreSQL deneyimi migration riskini düşürüyor. JSON kolonları sayesinde
esnek metadata saklayabiliyoruz.

### Sonuçlar

- Connection pooling için PgBouncer kurulumu gerekiyor
- Read replica stratejisi 6 ay içinde planlanmalı

EOF

Wiki’yi Güncel Tutmanın Pratik Yöntemleri

Dokümantasyonun eskimesi en yaygın sorun. Birkaç yaklaşım bu sorunu azaltıyor:

“Kod yazmadan önce wiki’yi aç” kuralı: Yeni bir özellik geliştirmeye başlamadan önce, o özelliğin wiki sayfasının taslağını oluşturun. Sayfayı [WIP] işareti ile açın. Kod tamamlanınca wiki’yi tamamlamak zorunda kalırsınız çünkü yarım bırakılmış sayfa görünür durumdadır.

Incident sonrası wiki güncellemesi: Her ciddi incident sonrasında yapılacaklar listesine “Wiki’deki sorun giderme sayfasını güncelle” maddesini ekleyin. Incident çözüm adımlarını doğrudan wiki’ye kopyalayın.

Periyodik review: Ayda bir, tüm wiki sayfalarını listeleyip “son 6 ayda değişmemiş ve aktif kullanılan” sayfaları review edin.

# Wiki'deki tüm sayfaların son commit tarihini listele
git clone https://github.com/kullaniciadiniz/projeadi.wiki.git
cd projeadi.wiki

for file in *.md; do
    last_commit=$(git log -1 --format="%ci" -- "$file")
    echo "${last_commit} | ${file}"
done | sort

Bu çıktıyı aylık olarak ekiple paylaştığınızda, uzun süredir güncellenmemiş sayfalar kendiliğinden göze çarpar.

Büyük Ekiplerde Wiki Yönetimi

Tek kişilik projelerde wiki yazmak kolaydır; asıl zorluk 10-15 kişilik ekiplerde yaşanır. Çakışmalar, tutarsız formatlar, kim neyi yazdı bilgisinin kaybolması gibi sorunlar ortaya çıkar.

Birkaç pratik önlem:

Sayfa sahipliği: Her wiki sayfasının en üstüne o sayfayı kimin güncellediğini not edin. Resmi bir prosedür değil, sadece bir konvansiyon. Sayfanın başına > Bakım Sorumlusu: @kullaniciadi gibi bir satır ekleyin.

Commit mesajı standardı: Wiki push’larında da anlamlı commit mesajı yazın. “Güncelleme” yerine “Kurulum sayfası: RHEL 9 SELinux adımı eklendi” yazın. Clone’ladığınızda git log --oneline çalıştırınca wiki’nin gelişimini görebilirsiniz.

Branch kullanımı: Büyük bir yeniden yapılandırma yapacaksanız, wiki’de de branch açabilirsiniz. Ancak GitHub arayüzü sadece master branch’i gösterir; bu yüzden branch’lar yalnızca review süreci için kullanışlıdır, yaşayan dokümantasyon için değil.

# Wiki'de branch oluşturup PR benzeri bir süreç simüle etmek
cd projeadi.wiki
git checkout -b mimari-dokuman-yenileme

# Değişikliklerinizi yapın...
git add .
git commit -m "Mimari sayfaları v2 formatına güncellendi"
git push origin mimari-dokuman-yenileme

# Ekip review'unun ardından merge edin
git checkout master
git merge mimari-dokuman-yenileme
git push origin master
git branch -d mimari-dokuman-yenileme
git push origin --delete mimari-dokuman-yenileme

Wiki’den Statik Site Üretmek

Bazı projelerde wiki içeriğini daha şık bir web sitesi olarak yayınlamak isteyebilirsiniz. Wiki zaten Markdown tabanlı olduğundan, MkDocs veya Docusaurus ile entegrasyon mümkündür.

# MkDocs ile wiki içeriğini statik siteye dönüştürme
# Önce wiki'yi ana repoya subtree olarak ekleyin

cd ana-proje-dizini

# Wiki'yi docs/ dizinine bağla
git remote add wiki https://github.com/kullaniciadiniz/projeadi.wiki.git
git fetch wiki

# Belirli bir wiki sayfasını docs'a kopyalayan basit bir script
cat > scripts/sync-wiki-to-docs.sh << 'EOF'
#!/bin/bash
WIKI_DIR="/tmp/wiki-sync-$$"
git clone https://github.com/kullaniciadiniz/projeadi.wiki.git "$WIKI_DIR"

# Home.md -> docs/index.md
cp "$WIKI_DIR/Home.md" docs/index.md

# Diğer sayfaları kopyala
for f in "$WIKI_DIR"/*.md; do
    fname=$(basename "$f")
    if [ "$fname" != "Home.md" ] && [[ ! "$fname" =~ ^_ ]]; then
        cp "$f" "docs/${fname}"
    fi
done

rm -rf "$WIKI_DIR"
echo "Wiki senkronizasyonu tamamlandı."
EOF

chmod +x scripts/sync-wiki-to-docs.sh

Sonuç

GitHub Wiki, araç kutusundaki en az kullanılan ama en değerli araçlardan biri. README dosyası “projeye nasıl merhaba denir” sorusunu cevaplar; Wiki ise “bu projeyle nasıl yaşanır” sorusunu. Kurulum detayları, mimari kararlar, operasyonel runbook’lar, incident geçmişi, API referansları, bunların hepsi için ayrı bir repo, ayrı bir platform aramanıza gerek yok.

Pratik önerim şu: Wiki’yi mükemmel hale getirmeye çalışarak başlamayın. Bugün, şu an, mevcut projenizin wiki’sini açın ve sadece bir sayfa yazın. En son yaşadığınız production sorununu, nasıl çözdüğünüzü, tekrar yaşanmaması için ne yapıldığını yazın. O tek sayfa, ileride birine en az birkaç saat kazandıracak. Oradan büyür zaten.

Dokümantasyonu sonra yazmak, hiç yazmamak anlamına gelir. Bunu zor yoldan öğrendim; siz öğrenmek zorunda değilsiniz.