Bir proje buldunuz. İhtiyacınızı karşılıyor gibi görünüyor. Ancak nasıl kurulacağı yazmıyor, hangi sürümleri gerektirdiği belirsiz ve çalıştırmanız gereken komutu bulamıyorsunuz.

Kod iyi olsa bile projeyi kullanmaya başlamak zorlaşıyor.

README dosyası, tam bu noktada devreye girer. Projeyi ilk kez gören kişiye neyle karşılaştığını, nasıl başlayacağını ve ihtiyaç duyduğunda nereden yardım alacağını anlatır.

Peki, README dosyası nasıl yazılır? Açık kaynak kalitesinde bir README, hangi bilgileri içermelidir?

Bu rehberde temel bölümleri adım adım oluşturacak, ardından kendi projenize uyarlayabileceğiniz bir şablon bulacaksınız.

README dosyası nedir?

README, bir yazılım projesinin amacını ve temel kullanımını açıklayan başlangıç belgesidir. Genellikle projenin ana klasöründe README.md adıyla bulunur.

.md uzantısı, dosyanın Markdown biçiminde yazıldığını belirtir. Markdown; başlık, liste, bağlantı ve kod örneklerini düz metin içinde kolayca düzenlemenizi sağlar.

README’nin ilk görevi, şu soruları yanıtlamaktır:

• Bu proje ne yapıyor?
• Kimler için ve hangi sorunu çözüyor?
• Nasıl kurulur ve çalıştırılır?
• Nasıl kullanılır?
• Sorunlar nasıl bildirilir ve katkı nasıl yapılır?
• Hangi lisans koşulları geçerlidir?

Her teknik ayrıntıyı bu dosyaya sığdırmanız gerekmez. README, ilk kullanım için yeterli bilgi sunmalı; kapsamlı konular için ilgili belgelere yönlendirmelidir.

1. Proje adını ve amacını açıkça yazın

İlk başlık proje adı olmalıdır. Hemen altındaki kısa açıklama, projenin ne yaptığını somut biçimde anlatmalıdır.

Şu açıklama yeterince bilgi vermez:

“Modern teknolojilerle geliştirilmiş yenilikçi bir uygulama.”

Bunun yerine kullanıcıya sunulan işlevi belirtin:

“Görev Defteri, günlük görevleri terminal üzerinden eklemenizi, listelemenizi ve tamamlandı olarak işaretlemenizi sağlayan bir komut satırı uygulamasıdır.”

Bu açıklama, okuyucunun projeye devam edip etmeyeceğine karar vermesini kolaylaştırır.

Proje henüz tamamlanmadıysa durumunu da belirtin. Örneğin “Deneysel sürüm; veri saklama biçimi değişebilir” gibi somut bir açıklama, beklentileri doğru kurar.

2. Temel özellikleri kısa bir listeyle gösterin

Özellikler bölümü, projenin sunduğu başlıca işlevleri hızlıca taramayı sağlar.

Örnek:

• Terminalden görev ekleme ve silme
• Tamamlanan görevleri işaretleme
• Görevleri yerel dosyada saklama
• Duruma göre görev filtreleme

Henüz geliştirilmemiş özellikleri bu listeye eklemeyin. Planlanan çalışmaları ayrı bir yol haritasında gösterin.

README, projenin bugünkü durumunu doğru yansıtmalıdır.

3. Kurulumdan önce gereksinimleri belirtin

Okuyucunun kurulum sırasında eksik bir araç veya uyumsuz bir sürümle karşılaşmasını önlemek için ön koşulları açıklayın.

Projeye göre şu bilgiler gerekli olabilir:

• Programlama dili veya çalışma ortamı
• Desteklenen sürümler
• Paket yöneticisi
• Veritabanı veya harici servis
• İşletim sistemine özgü gereksinimler

“Python kurulu olmalı” yerine, projenin gerçekten desteklediği sürüm aralığını yazın. Sürüm bilgilerini proje yapılandırması ve test sonuçlarıyla tutarlı tutun.

Harici servis gerekmiyorsa bunu belirtmek de yararlıdır:

“Uygulama verileri yerel dosyada saklar; ayrı bir veritabanı kurulumu gerektirmez.”

4. Kurulum adımlarını çalıştırılabilir sırayla verin

Kurulum bölümü, okuyucunun sıfırdan başlayarak projeyi hazırlamasını sağlamalıdır.

Adımlar çoğunlukla şu sırayı izler:

1. Projeyi bilgisayara indirin.
2. Proje klasörüne geçin.
3. Bağımlılıkları yükleyin.
4. Gerekli yapılandırmayı hazırlayın.
5. Uygulamayı başlatın.

Komutların hangi klasörde çalıştırılacağını açıklayın. Bir önceki adımda oluşturulmayan dosyayı veya kurulmamış bir aracı sonraki adımda varmış gibi kullanmayın.

İşletim sistemlerine göre komutlar farklıysa alternatifleri ayrı gösterin. Özellikle dosya kopyalama, ortam değişkeni tanımlama ve sanal ortam etkinleştirme adımlarında bu farklar önemlidir.

Yapılandırma dosyalarını açıklayın

Proje ortam değişkenleri kullanıyorsa değişkenlerin adlarını ve amaçlarını yazın. Bir .env.example dosyası varsa README’den bağlantı verin.

Örnek değerlerle gerçek kimlik bilgilerini ayırın. Parola veya API anahtarı gereken alanlarda YOUR_API_KEY gibi belirgin yer tutucular kullanın.

Ayrıca .env dosyasını oluşturmanın tek başına yeterli olup olmadığını açıklayın. Uygulamanın bu dosyayı nasıl okuduğu, kullanılan yapıya bağlıdır.

5. İlk başarılı kullanımı gösterin

Kurulumun tamamlanması, okuyucunun uygulamayı kullanabildiği anlamına gelmez. En az bir küçük kullanım örneği ekleyin.

Örneğin bir görev uygulaması için örnek akış şöyle olabilir:

gorev ekle "README dosyasını hazırla"
gorev listele

Beklenen çıktıyı da gösterin:

1. [ ] README dosyasını hazırla

Bu komutlar örnek bir uygulamaya aittir; kendi README’nizde projenizin gerçek komutlarını kullanın.

İyi bir kullanım örneği, hem yapılacak işlemi hem de başarılı sonucun nasıl göründüğünü anlatır. Böylece okuyucu kurulumun doğru çalıştığını kontrol edebilir.

Görsel arayüzü olan projelerde ekran görüntüsü de ekleyebilirsiniz. Görsele kısa bir açıklama yazın ve önemli kullanım adımlarını metin olarak da sunun.

6. Test ve sorun giderme bilgilerini ekleyin

Katkı sunmak isteyen bir geliştirici, yaptığı değişikliğin mevcut davranışı bozup bozmadığını kontrol edebilmelidir.

Test bölümü şunları açıklamalıdır:

• Testler hangi komutla çalıştırılır?
• Ek hazırlık gerekir mi?
• Harici servis veya test veritabanı kullanılır mı?

Test altyapısı henüz yoksa çalışmayan bir test komutu eklemeyin. Mevcut durumu açıkça belirtin.

Sorun giderme bölümünü ise gerçek karşılaşılan sorunlarla oluşturun. Her maddeyi şu yapıda yazabilirsiniz:

Belirti → Olası neden → Çözüm

Örneğin “Komut bulunamadı” hatası için aracın kurulumu veya çalıştırıldığı ortam kontrol edilebilir. Çözümü projenizin gerçek kurulum yöntemine göre açıklayın.

7. Katkı ve lisans bilgilerini görünür kılın

Açık kaynak projelerde okuyucu yalnızca kullanıcı olmayabilir. Hata bildirmek, belgeyi düzeltmek veya yeni özellik geliştirmek isteyebilir.

Katkı bölümünde başlangıç yolunu açıklayın:

• Hatalar nereye bildirilir?
• Özellik önerileri nasıl paylaşılır?
• Değişiklik gönderilmeden önce hangi kontroller yapılır?

Ayrıntılı kurallar varsa README’yi uzatmak yerine CONTRIBUTING.md dosyasına bağlantı verin.

Lisans bölümünde de projenin gerçek lisansını belirtin ve ilgili dosyaya bağlantı ekleyin. Şablondaki bir lisans adını kontrol etmeden kopyalamayın; README ile lisans dosyası tutarlı olmalıdır.

Kopyalanabilir README şablonu

Aşağıdaki şablondaki köşeli parantezli alanları projenize göre doldurun. Gereksiz bölümleri kaldırın ve komut alanlarına doğruladığınız komutları ekleyin.

# [Proje Adı]

[Projenin ne yaptığını, kimler için olduğunu ve hangi sorunu çözdüğünü
bir veya iki cümleyle açıklayın.]

**Proje durumu:** [Geliştirme aşamasında / Deneysel / Kullanıma hazır]

## Özellikler

- [Mevcut özellik 1]
- [Mevcut özellik 2]
- [Mevcut özellik 3]

## Gereksinimler

- [Çalışma ortamı ve desteklenen sürümler]
- [Paket yöneticisi]
- [Varsa gerekli servisler]

## Kurulum

1. Depoyu bilgisayarınıza indirin:

   ```bash
   git clone [DEPO_URL]
   cd [PROJE_KLASORU]
   ```

2. Bağımlılıkları yükleyin:

   ```text
   [BAĞIMLILIK_YÜKLEME_KOMUTU]
   ```

3. [Varsa yapılandırma dosyasını hazırlama adımlarını açıklayın.]

4. Uygulamayı başlatın:

   ```text
   [BAŞLATMA_KOMUTU]
   ```

## Yapılandırma

[Bu bölüm gerekmiyorsa kaldırın.]

| Değişken | Açıklama | Zorunlu mu? | Varsayılan |
| --- | --- | --- | --- |
| [DEĞİŞKEN_ADI] | [Ne için kullanılır?] | [Evet/Hayır] | [Varsa değer] |

[Değişkenlerin nasıl tanımlandığını ve uygulamaya nasıl
aktarıldığını açıklayın. Gerçek kimlik bilgileri eklemeyin.]

## Kullanım

[En yaygın kullanım senaryosunu açıklayın.]

```text
[ÇALIŞAN_KULLANIM_ÖRNEĞİ]
```

Beklenen sonuç:

```text
[ÖRNEK_ÇIKTI]
```

## Testler

[Varsa test ön koşullarını açıklayın.]

```text
[TEST_KOMUTU]
```

## Sorun Giderme

### [Sık karşılaşılan hata veya belirti]

- Olası neden: [Açıklama]
- Çözüm: [Uygulanabilir adımlar]

## Katkıda Bulunma

[Hata bildirme, öneri paylaşma ve değişiklik gönderme sürecini açıklayın.]

[Varsa katkı rehberine bağlantı ekleyin.]

## Lisans

[Lisans adını belirtin ve lisans dosyasına bağlantı ekleyin.]

## Destek

[Sorular için kullanılacak issue, tartışma veya iletişim kanalını belirtin.]

README yazarken sık yapılan hatalar

Yalnızca teknoloji listesini paylaşmak

Kullanılan dil ve araçlar yararlı bilgilerdir. Ancak okuyucu önce projenin ne işe yaradığını öğrenmelidir. Açılışı teknoloji listesi yerine amaç ve kullanım alanıyla yapın.

Kurulumu kendi bilgisayarınıza göre anlatmak

Bilgisayarınızda zaten kurulu olan araçlar, yeni bir kullanıcıda bulunmayabilir. Kurulum adımlarını mümkünse temiz bir ortamda deneyin.

Çalışmayan veya eksik örnekler bırakmak

Dosya yolları, komutlar ve seçenekler zamanla değişebilir. Kullanımı etkileyen bir değişiklik yaptığınızda README örneklerini de güncelleyin.

Her ayrıntıyı aynı dosyada toplamak

Uzun API açıklamaları ve kapsamlı mimari kararlar, ilk kullanım adımlarını bulmayı zorlaştırabilir. Ayrıntıları ayrı belgelere taşıyıp README’den bağlantı verin.

Sık sorulan sorular

README dosyası hangi formatta yazılır?

Yaygın tercih Markdown biçimindeki README.md dosyasıdır. Başlık, liste, bağlantı, tablo ve kod bloklarıyla düzenli bir belge oluşturabilirsiniz.

README ne kadar uzun olmalı?

Sabit bir uzunluk hedefi yoktur. Okuyucunun projeyi anlaması ve ilk başarılı kullanıma ulaşması için gereken bilgileri içermelidir. Küçük bir araç kısa bir belgeyle açıklanabilir; daha karmaşık bir proje ek rehberlere ihtiyaç duyabilir.

README Türkçe mi, İngilizce mi olmalı?

Hedef kitlenize göre karar verin. Türkçe konuşan kullanıcılara yönelik bir projede Türkçe uygundur. Uluslararası katkı hedefliyorsanız İngilizce bir sürüm hazırlayabilir, iki belge arasında bağlantı kurabilirsiniz.

Her projede rozet kullanmak gerekir mi?

Hayır. Test durumu veya yayımlanan sürüm gibi yararlı bilgiler sunan rozetler eklenebilir. Açık bir proje açıklaması ve çalışan kurulum adımları daha temel ihtiyaçlardır.

README’nizi ilk kez gelen bir kullanıcı gibi deneyin

Dosyayı tamamladıktan sonra projeyi yeni bir klasöre indirin ve yalnızca README’deki adımları izleyin. Aklınızdaki bilgileri kullanarak atladığınız bir işlem olursa onu da belgeye ekleyin.

Son kontrolde proje amacı, gereksinimler, kurulum komutları, kullanım örnekleri ve bağlantıların güncel olduğundan emin olun.

İyi bir README, okuyucunun projeyi anlamasını ve ilk adımı kendi başına atmasını sağlar. Bu nedenle README’yi hazırlamayı, projenin kullanılabilirliğini geliştiren bir çalışma olarak ele alın.