README içinde lisans bölümü şart mı?

Kısa bir bölüm faydalı ama tek başına yeterli değil. Asıl belirleyici olan repo kökündeki LICENSE dosyası; GitHub lisansı oradan okuyor ve arayüzde onu gösteriyor. README'deki iki satır ise okuyucuyu o dosyaya yönlendiriyor. Araç lisans alanını doldurduğunuzda ikisi de tutarlı olacak şekilde tek satırlık bir bölüm üretiyor.

README'ye ekran görüntüsü koymalı mıyım?

Görsel çıktısı olan bir proje ise evet, bir tane koyun. CLI aracıysa terminal çıktısının kendisi bir kod bloğu olarak ekran görüntüsünden daha iyi iş görüyor, çünkü kopyalanabiliyor ve aranabiliyor. Kütüphane ise görsel gerekmiyor, onun yerine gerçek bir kullanım örneği koyun. Görsel koyacaksanız GIF yerine statik PNG tercih edin, sayfa çok daha hızlı açılıyor.

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

Hedef kitleye bakın. Yalnızca Türkiye'deki bir ekip kullanacaksa Türkçe daha doğru. Uluslararası katkı bekliyorsanız veya paketi npm gibi bir kayıt defterine yayınlıyorsanız İngilizce. İkisini birden istiyorsanız README.md İngilizce, README.tr.md Türkçe olsun ve iki dosyanın başına birbirine giden bir satır ekleyin. Bu araç iki dilde de çıktı üretiyor ve içindekiler anchor'ları her iki durumda da doğru kalıyor.

README ne kadar uzun olmalı?

Kesin bir sayı yok ama pratik bir ölçüt var: okuyucu kurulum komutuna ulaşmak için üçten fazla kaydırma yapıyorsa dosya uzamış demektir. Küçük bir kütüphane için 50 ile 150 satır arası fazlasıyla yeterli. Bunun ötesine geçen her şey aslında dokümantasyon ve ayrı bir yere ait.

CONTRIBUTING dosyası ayrıca gerekli mi?

Dışarıdan pull request bekliyorsanız evet. GitHub, CONTRIBUTING.md dosyasını tanıyor ve yeni bir issue veya pull request açılırken katkı sağlayana gösteriyor. README'deki kısa katkı bölümü kapıyı açık tuttuğunuzu belirtiyor, CONTRIBUTING ise kod stili, test çalıştırma ve commit kuralları gibi ayrıntıları taşıyor. Araç katkı bölümünü isteğe bağlı üretiyor; işaretlerseniz fork, branch, commit, pull request adımlarını numaralı liste olarak ekliyor.

README Oluşturucu

Kısa bir formdan eksiksiz bir README.md üretin: rozetler, kurulum adımları, kullanım, lisans. Canlı Markdown önizlemesiyle, sunucuya hiçbir veri gitmeden.

Veriler tarayıcınızdan çıkmazGüncelleme: Temmuz 2026

Paket yöneticisi

Proje adı

Depo (kullanici/repo)

Tek satırlık tanım

Açıklama

Özellikler

Gereksinimler

Her satır bir madde olur.

Lisans

Yazar

Yıl

Eklenecekler

Rozetler

İçindekiler

Katkı bölümü

README.md

# Project

## İçindekiler

- [Kurulum](#kurulum)
- [Kullanım](#kullanım)
- [Katkı](#katkı)
- [Lisans](#lisans)

## Kurulum

```bash
npm install
```

## Kullanım

```bash
npm run dev
```

## Katkı

Katkılar memnuniyetle karşılanır. Büyük bir değişiklik planlıyorsanız önce bir issue açıp ne yapmak istediğinizi anlatın.

1. Repoyu fork edin
2. Bir branch açın (`git checkout -b ozellik/kisa-aciklama`)
3. Değişikliklerinizi commit edin
4. Branch'i push edip pull request açın

## Lisans

MIT lisansı ile dağıtılmaktadır. Ayrıntılar için `LICENSE` dosyasına bakın.

Yalnızca doldurduğunuz bölümler dosyaya girer, böylece içi "TODO" başlıklarıyla dolu bir README oluşmaz. Rozetler için depo alanının dolu olması gerekir.

Özet (TL;DR)

README yazmanın zor kısmı prose değil, hangi bölümlerin gerçekten gerektiğine karar vermek; bu araç boş kalan bölümü hiç üretmiyor.
Rozet sayısı 4 civarında tutulduğunda işe yarıyor: lisans, yıldız, açık issue, son commit. 15 rozet üst üste kimsenin okumadığı bir duvar.
Kurulum bloğu clone satırıyla birlikte kopyalanabilir olmalı; araç git clone, cd ve install komutunu tek fenced blokta üretiyor.
GitHub başlık anchor'larını Türkçe harfleri ASCII'ye çevirmeden üretir, bu yüzden ## Kurulum anchor'ı #kurulum olur ve içindekiler tablosu çalışır.

README neden yarıda kalıyor

Projeyi bitirip repoyu public yaptıktan sonra README'ye oturuyorsunuz, başlığı ve bir cümlelik açıklamayı yazıyorsunuz, sonra duruyorsunuz. Takılınan yer genelde şu oluyor: hangi bölümün gerçekten gerektiği netleşmeden dosya büyüyor. "Roadmap" mi koysam, "Acknowledgements" mı, screenshot şart mı? Karar verilemeyince dosya "## Usage" başlığı ve altında boş bir satırla depoda kalıyor.

Formun mantığı bu kararı sizin yerinize vermek üzerine kurulu. Bir alanı boş bırakırsanız o bölüm çıktıda hiç yer almıyor. Özellik listesi girmediyseniz "Özellikler" başlığı basılmıyor, gereksinim yazmadıysanız "Gereksinimler" yok. Yani elinizde "TODO" ile dolu bir iskelet değil, kısa ama eksiksiz bir dosya kalıyor.

İlk 30 saniyede okuyucuya borçlu olduğunuz şey

Repoya ilk kez gelen biri üç soruya cevap arıyor: bu ne işe yarıyor, bende çalışır mı, nasıl kurarım. Üçü de ekranın ilk yüksekliğinde olmalı. Proje adı, tek satırlık tagline, kısa açıklama ve hemen ardından kurulum. Mimarî anlatımı, tasarım kararları, benchmark tabloları aşağıya iner ya da ayrı bir dosyaya gider.

Kurulum bloğunda en sık gözden kaçan şey clone satırı. Depo sahibi kendi makinesinde zaten repo içinde olduğu için npm install yazıp geçiyor, ama gelen kişi henüz dosyaları indirmedi. Araç bu yüzden repo alanını doldurduğunuzda üç satırı birlikte basıyor:

bash

1git clone https://github.com/kullanici/proje.git2cd proje3npm install

Blok olduğu gibi seçilip terminale yapıştırıldığında çalışıyor. Paket yöneticisini yarn, pnpm veya bun seçerseniz install komutu ona göre değişiyor; kendi komutunuzu yazarsanız varsayılanın yerine o geçiyor.

Rozet yorgunluğu

Rozetler bilgi taşıdığı sürece iyi. Sorun, aynı satırda 15 tane olunca hiçbirinin okunmaması. Araç dört tane basıyor ve hepsi repo verisinden otomatik geliyor: lisans, yıldız sayısı, açık issue sayısı, son commit tarihi. Bunların dördü de "bu proje bakımda mı" sorusuna cevap veriyor, ki ilk ziyaretçinin gerçekten merak ettiği şey bu.

Bilgi

Rozetlerin shields.io üzerinden üretildiğini ve owner/repo yolunu doğru yazmanız gerektiğini unutmayın. Alan boş kalırsa rozet bloğu hiç basılmıyor, bozuk görsel yerine hiç görsel gelmiş oluyor.

README ile dokümantasyon aynı şey değil

README bir tanıtım ve hızlı başlangıç sayfası. Dokümantasyon ise referans: her fonksiyonun imzası, her yapılandırma anahtarı, her hata kodu. İkisini tek dosyaya sıkıştırmaya çalıştığınızda ortaya 900 satırlık, ne tanıtım ne referans olan bir şey çıkıyor. Ölçüt basit: README ekranda birkaç kaydırmada bitmeli. Fazlası docs/ klasörüne veya bir wiki'ye.

Bölüm	README	Dokümantasyon
Ne işe yarar	Var, iki üç cümle	Var, genişletilmiş
Kurulum	Var, kopyalanabilir	Platform bazlı ayrıntı
API referansı	Yok, sadece bir örnek	Tam liste
Yapılandırma anahtarları	En kritik 2-3 tanesi	Hepsi, varsayılanlarıyla
Sorun giderme	Yok	Var

README ziyaretçiyi karara götürür, dokümantasyon kullanıcıyı işine döndürür.

İçindekiler ve anchor eşleşmesi

GitHub, Markdown başlıklarından otomatik anchor üretiyor: küçük harfe çeviriyor, noktalama işaretlerini atıyor, boşlukları tireye dönüştürüyor. Buradaki ayrıntı şu: Türkçe harfler ASCII'ye katlanmıyor. ## Kurulum ve Çalıştırma başlığının anchor'ı #kurulum-ve-çalıştırma oluyor, #kurulum-ve-calistirma değil. Elle içindekiler yazan çoğu kişi burada Türkçe karakterleri sadeleştiriyor ve linkler sessizce sayfanın başına atıyor.

markdown

1## İçindekiler2 3- [Kurulum ve Çalıştırma](#kurulum-ve-calistirma)   <!-- link ölü -->4- [Kurulum ve Çalıştırma](#kurulum-ve-çalıştırma)   <!-- doğrusu -->5 6## Kurulum ve Çalıştırma

Araç içindekiler tablosunu başlıkların kendisinden türettiği için bu ikisi hiçbir zaman ayrışmıyor. Bir de eşiği var: bölüm sayısı ikiden fazla değilse içindekiler basılmıyor, çünkü üç maddelik bir içindekiler listesi sayfayı uzatmaktan başka bir işe yaramıyor.

Sıkça Sorulan Sorular

README içinde lisans bölümü şart mı?: Kısa bir bölüm faydalı ama tek başına yeterli değil. Asıl belirleyici olan repo kökündeki LICENSE dosyası; GitHub lisansı oradan okuyor ve arayüzde onu gösteriyor. README'deki iki satır ise okuyucuyu o dosyaya yönlendiriyor. Araç lisans alanını doldurduğunuzda ikisi de tutarlı olacak şekilde tek satırlık bir bölüm üretiyor.
README'ye ekran görüntüsü koymalı mıyım?: Görsel çıktısı olan bir proje ise evet, bir tane koyun. CLI aracıysa terminal çıktısının kendisi bir kod bloğu olarak ekran görüntüsünden daha iyi iş görüyor, çünkü kopyalanabiliyor ve aranabiliyor. Kütüphane ise görsel gerekmiyor, onun yerine gerçek bir kullanım örneği koyun. Görsel koyacaksanız GIF yerine statik PNG tercih edin, sayfa çok daha hızlı açılıyor.
README Türkçe mi İngilizce mi olmalı?: Hedef kitleye bakın. Yalnızca Türkiye'deki bir ekip kullanacaksa Türkçe daha doğru. Uluslararası katkı bekliyorsanız veya paketi npm gibi bir kayıt defterine yayınlıyorsanız İngilizce. İkisini birden istiyorsanız README.md İngilizce, README.tr.md Türkçe olsun ve iki dosyanın başına birbirine giden bir satır ekleyin. Bu araç iki dilde de çıktı üretiyor ve içindekiler anchor'ları her iki durumda da doğru kalıyor.
README ne kadar uzun olmalı?: Kesin bir sayı yok ama pratik bir ölçüt var: okuyucu kurulum komutuna ulaşmak için üçten fazla kaydırma yapıyorsa dosya uzamış demektir. Küçük bir kütüphane için 50 ile 150 satır arası fazlasıyla yeterli. Bunun ötesine geçen her şey aslında dokümantasyon ve ayrı bir yere ait.
CONTRIBUTING dosyası ayrıca gerekli mi?: Dışarıdan pull request bekliyorsanız evet. GitHub, CONTRIBUTING.md dosyasını tanıyor ve yeni bir issue veya pull request açılırken katkı sağlayana gösteriyor. README'deki kısa katkı bölümü kapıyı açık tuttuğunuzu belirtiyor, CONTRIBUTING ise kod stili, test çalıştırma ve commit kuralları gibi ayrıntıları taşıyor. Araç katkı bölümünü isteğe bağlı üretiyor; işaretlerseniz fork, branch, commit, pull request adımlarını numaralı liste olarak ekliyor.