İyi bir README: projeni ilk 30 saniyede anlatmak

GitHub'da bir depoya ilk gelen kişi kodu okumaz, README'yi okur. Bu kişi seni işe alacak biri, projene katkı vermek isteyen bir geliştirici ya da üç ay sonra projeyi yeniden kurmaya çalışan sen olabilirsin. Üçü de aynı şeyi soruyor: bu proje ne yapıyor, nasıl çalıştırılıyor, ben ne yapabilirim? İyi bir README bu üç soruyu ilk otuz saniyede cevaplar.

README neden bu kadar önemli?

GitHub, deponun kök dizinindeki (ya da .github veya docs klasöründeki) README dosyasını depo sayfasında kodun hemen altında otomatik olarak gösterir. GitHub'ın belgelerinde de anlatıldığı gibi, README genellikle ziyaretçinin gördüğü ilk şeydir.

CV'ne bir proje bağlantısı koyduysan, o bağlantıyı tıklayan kişinin göreceği şey README'dir. Bomboş bir README ya da framework'ün otomatik oluşturduğu "This project was bootstrapped with…" metni, projen ne kadar iyi olursa olsun yarım kalmış gibi görünür.

Sırayla: bir README'de neler olmalı?

1. Ad ve tek cümlelik açıklama

En üstte projenin adı ve ne yaptığını anlatan tek bir cümle. "Kampüste kaybolan eşyaları ilan ve konumla eşleştiren mobil uygulama." Teknoloji listesi değil, ne işe yaradığı.

2. Ekran görüntüsü ya da kısa bir GIF

Bir arayüzü olan projede tek bir ekran görüntüsü, üç paragraf açıklamadan daha hızlı anlatır. Görselleri depoda bir klasöre (örneğin docs/) koyup göreli bağlantıyla ekleyebilirsin. Canlı bir demo varsa bağlantısını da buraya koy.

3. Özellikler

Üç ila altı maddelik kısa bir liste. Kullanıcının yapabildiklerini yaz: "İlan oluşturma", "Konuma göre arama", "Eşleşme bildirimi".

4. Kurulum ve çalıştırma

README'lerin en çok eksik kalan bölümü bu. Projeyi hiç görmemiş biri, yalnızca bu bölümü takip ederek projeyi kendi bilgisayarında çalıştırabilmeli. Gereksinimleri (dil sürümü, veritabanı) ve komutları sırayla yaz:

git clone https://github.com/kullanici/kayip-esya.git
cd kayip-esya
cp .env.example .env   # gerekli değişkenleri doldur
docker compose up -d   # veritabanını başlatır
./gradlew bootRun      # API http://localhost:8080 adresinde açılır

Ortam değişkenleri gerekiyorsa gerçek değerleri değil, örnek bir .env.example dosyasını depoya koy ve README'de ondan bahset. Şifreleri, API anahtarlarını asla depoya yükleme.

5. Kullanılan teknolojiler ve mimari

Kısa bir liste yeter. Proje birden fazla parçadan oluşuyorsa (mobil uygulama, API, veritabanı) iki üç cümleyle nasıl bir araya geldiklerini anlat. Basit bir şema varsa daha da iyi.

6. Katkı ve iletişim

Projeye katkı almak istiyorsan nasıl yapılacağını yaz: issue açmak, branch adlandırma, pull request kuralları. Uzunsa ayrı bir CONTRIBUTING.md dosyasına taşı ve README'den bağlantı ver. GitHub bu dosyayı da tanıyor ve issue ya da pull request açan kişiye gösteriyor.

7. Lisans

Açık kaynak bir proje ise hangi lisansla yayınladığını belirt ve kök dizine bir LICENSE dosyası ekle. Lisans dosyası olmayan bir depoda kodun nasıl kullanılabileceği belirsiz kalır.

Kopyalayıp başlayabileceğin iskelet

# Proje Adı

Tek cümlede ne yaptığı.

![Ekran görüntüsü](docs/ekran.png)

## Özellikler
- ...
- ...

## Kurulum
Gereksinimler: ...

```bash
git clone ...
...
```

## Teknolojiler
- ...

## Katkı
Issue açabilir ya da pull request gönderebilirsin. Ayrıntılar: CONTRIBUTING.md

## Lisans
MIT

Sık yapılan hatalar

• Kurulum adımlarını denememek: README'yi yazdıktan sonra depoyu boş bir klasöre yeniden klonla ve yalnızca README'deki adımları izle. Takıldığın yer, okuyanın da takılacağı yerdir.
• Güncel tutmamak: Komut ya da bağımlılık değiştiğinde README'yi aynı commit'te güncelle.
• Fazla uzun yazmak: README bir ders kitabı değil. Ayrıntılı belgeler için docs/ klasörü ya da bir wiki daha uygun.

Profil README'si de var

GitHub'da kullanıcı adınla aynı isimde herkese açık bir depo açıp içine README koyarsan, o dosya profil sayfanın en üstünde görünür. Kim olduğunu, ne üzerinde çalıştığını ve en iyi iki üç projeni orada kısaca anlatabilirsin. Profiline gelen bir işe alımcı için iyi bir başlangıç noktası.

Bu hafta dene

En sevdiğin projeni aç ve README'sini bu yazıdaki sırayla baştan yaz. Sonra bir arkadaşından, projeyi hiç bilmeden yalnızca README'ye bakarak çalıştırmasını iste. Nerede sorduğu, README'nin nerede eksik olduğunu gösterir.

README'ni ve projeni başkalarının gözüyle görmek istersen re:make her pazar 15.00'te Buca'da buluşuyor; projeler orada birlikte didikleniyor. Üye olmadan da gelebilirsin. Yeri ve saati burada.