Profesyonel README Yazma Rehberi: GitHub Projelerinizi Bir Üst Seviyeye Taşıyın

Giriş

• Bir GitHub repository’sine girdiğinizde gördüğünüz ilk şey genellikle kodlar değildir.
• README dosyasıdır.
• Birçok geliştirici saatlerce proje geliştirir.
• Ancak README kısmına yalnızca şu satırı yazar:

My Project

veya

Python Project

• Bu büyük bir hatadır.

Çünkü README dosyası:

• Projenizin vitrini
• İlk izlenim noktası
• Kullanım kılavuzu
• Dokümantasyonu
• Tanıtım sayfasıdır

Bu yazıda profesyonel seviyede README hazırlamayı öğreneceğiz.

README Nedir?

• README.md dosyası bir projenin tanıtım dosyasıdır.
• GitHub repository açıldığında otomatik olarak görüntülenir.
• Bir ziyaretçi genellikle şu sırayla hareket eder:

README
↓
Ekran görüntüleri
↓
Kurulum
↓
Kodlar

• Bu nedenle README kalitesi projenin algısını doğrudan etkiler.

Kötü README Örneği

Python Project

Bu kadar.

• Ziyaretçi:

Bu proje ne yapıyor?
Nasıl çalışıyor?
Nasıl kurulur?

sorularının hiçbirine cevap bulamaz.

İyi README Ne Sağlar?

İyi bir README:

• Projeyi açıklar
• Kullanıcıyı yönlendirir
• Kurulumu anlatır
• Teknolojileri gösterir
• Katkı sürecini açıklar

README Yazarken İlk Kural

• Kendinize şu soruyu sorun:

Bu projeyi ilk kez gören biri ne bilmek ister?

• README bunun cevabıdır.

Profesyonel README Yapısı

• En yaygın yapı:

Proje Başlığı
Açıklama
Özellikler
Teknolojiler
Kurulum
Kullanım
Ekran Görüntüleri
Proje Yapısı
Katkı Sağlama
Lisans
İletişim

1. Proje Başlığı

• README’nin en üst kısmında bulunur.

Örnek:

# Öğrenci Yönetim Sistemi

2. Proje Açıklaması

• Kısa ve net olmalıdır.

Örnek:

Bu proje Python kullanılarak geliştirilmiş basit bir öğrenci yönetim sistemidir.

• Bir ziyaretçi ilk 5 saniyede projenin ne yaptığını anlamalıdır.

3. Özellikler Bölümü

• Kullanıcının neler yapabileceğini anlatır.

Örnek:

## Özellikler

- Öğrenci ekleme
- Öğrenci silme
- Öğrenci güncelleme
- Öğrenci listeleme

4. Kullanılan Teknolojiler

• Bu bölüm çok önemlidir.

Örnek:

## Teknolojiler

- Python
- Pandas
- NumPy
- Streamlit

• İnsanlar projenin hangi teknolojilerle geliştirildiğini görmek ister.

5. Kurulum Bölümü

• En kritik bölümlerden biridir.
• Bir kullanıcı projeyi çalıştırmak istediğinde ilk baktığı yer burasıdır.

Kötü Kurulum Örneği

Projeyi çalıştırın.

• Bu hiçbir şey anlatmaz.

İyi Kurulum Örneği

## Kurulum

Repository'yi klonlayın:

git clone PROJE_URL

Proje klasörüne girin:

cd proje

Gerekli paketleri yükleyin:

pip install -r requirements.txt

Uygulamayı çalıştırın:

python app.py

6. Kullanım Bölümü

• Kurulumdan sonra kullanıcı ne yapacak?

Örnek:

## Kullanım

Uygulama açıldığında yeni öğrenci ekleyebilir ve mevcut öğrencileri görüntüleyebilirsiniz.

7. Ekran Görüntüleri

• README’nin en çok dikkat çeken bölümlerinden biridir.

Özellikle:

• Web projeleri
• Veri analizi projeleri
• Mobil uygulamalar

için çok önemlidir.

Ekran Görüntüsü Nasıl Eklenir?

Örnek:

## Ekran Görüntüleri

![Ana Sayfa](images/homepage.png)

Ne Tür Görseller Eklenmeli?

Örnek:

• Ana ekran
• Dashboard
• Grafikler
• Sonuç ekranları

8. Proje Yapısı

• Özellikle büyük projelerde kullanılır.

Örnek:

project
│
├── data
├── notebooks
├── src
├── app.py
├── requirements.txt
└── README.md

• Bu yapı kullanıcıya projeyi hızlıca anlamasını sağlar.

9. Katkı Sağlama

• Açık kaynak projelerde önemlidir.

Örnek:

## Katkı Sağlama

Katkıda bulunmak için repository'yi fork edin ve Pull Request oluşturun.

10. Lisans

• Profesyonel projelerde mutlaka bulunmalıdır.

Örnek:

## Lisans

Bu proje MIT lisansı ile lisanslanmıştır.

Rozetler (Badges)

• GitHub’da sık gördüğünüz küçük etiketlerdir.

Örnek:

Python
MIT License
Version 1.0
Build Passing

• Bu rozetler projeyi daha profesyonel gösterir.

README’de Emojiler Kullanılmalı mı?

• Evet.
• Ancak abartılmamalıdır.

İyi örnek:

## 📊 Özellikler

## 🛠 Teknolojiler

Kötü örnek:

🚀🔥💯🎉⭐✨⚡🚀🔥💯🎉⭐✨⚡

README Uzunluğu Ne Kadar Olmalı?

• Küçük projeler:

300–600 kelime

• Orta ölçekli projeler:

600–1500 kelime

• Büyük projeler:

1500+ kelime

Veri Bilimi Projelerinde README

• Özellikle şu bölümler eklenmelidir:

## Veri Seti

## Veri Temizleme

## Özellik Mühendisliği

## Model Sonuçları

## Performans Metrikleri

Web Projelerinde README

• Şunlar mutlaka olmalıdır:

## Özellikler

## Kurulum

## API Bilgileri

## Ekran Görüntüleri

## Deployment

Portföy Projelerinde README

Amaç:

Kod göstermek değil,
yetkinlik göstermek.

• Bu nedenle proje amacı mutlaka açıklanmalıdır.

Profesyonel README Şablonu

# Proje Adı

Kısa proje açıklaması.

## Özellikler

- Özellik 1
- Özellik 2
- Özellik 3

## Kullanılan Teknolojiler

- Python
- Pandas
- NumPy

## Kurulum

git clone REPO_URL

cd proje

pip install -r requirements.txt

python app.py

## Kullanım

Uygulama hakkında bilgiler.

## Ekran Görüntüleri

Görseller

## Proje Yapısı

Dosya yapısı

## Katkı Sağlama

Katkı süreci

## Lisans

MIT

Sonuç

• README dosyası çoğu kişinin düşündüğünden çok daha önemlidir.
• Bir ziyaretçi kodlarınızı incelemeden önce README’nizi okur.

İyi hazırlanmış bir README:

• Projenizi daha profesyonel gösterir
• Kullanıcı deneyimini artırır
• İş başvurularında olumlu izlenim bırakır
• Açık kaynak katkılarını kolaylaştırır

Kodlarınız ne kadar iyi olursa olsun, README dosyanız zayıfsa projenizin değeri olduğundan daha düşük algılanabilir.

Bu yüzden her projeye bir README değil, iyi bir README yazmaya çalışın.